Merge remote-tracking branch 'origin/master' into codex/fs-directory-listing

# Conflicts: # docs/rfc/README.md # packages/fs/fs-local/src/index.ts
2026-07-04 00:56:17 +08:00
parent 5dfe09959d 26f8d1b9b6
commit bf1966326e
90 changed files with 4283 additions and 1192 deletions
--- a/docs/cookbook/adding-a-tool.md
+++ b/docs/cookbook/adding-a-tool.md
@@ -36,6 +36,7 @@ Registration is effect-based: disposing the plugin fiber unregisters the tool (w
 - **Args are validated for you.** `defineTool` validates the model-generated `arguments` against the `SchemaSpec` before `execute` runs (type, required keys, enum membership, nested objects/arrays — [runtime arg validation](../rfc/implemented/architecture/2026-06-11-runtime-arg-validation.md)), so inside `execute` the args already match `InferArgs`. You still hand-check value constraints the DSL can't express (non-empty strings, positive numbers, cross-field rules); throw a descriptive Error for those. Raw JSON-Schema tools registered directly (MCP) are NOT validated by the harness — they validate their own input.
 - **Throwing means isError.** The registry catches anything `execute()` throws and returns `{isError: true}` to the model. Use that for infrastructure failures (bad input, spawn errors, aborts) — but REPORT domain failures in the result text instead (e.g. tool-bash returns `[exit code: 9]` with `isError: false`: the model decides what a failing command means).
 - **Honor `exec.signal`.** Cancel in-flight work when it fires.
+- **Attach durable card data with `meta` (optional).** `execute` may return `{ content, meta }` instead of a bare `ContentBlock[]` — `meta` is a JSON-serializable payload the core treats as opaque, persisted on the `tool/result` event and handed back to your `presentResult` (so a card that needs more than `args`, like `write`/`edit`'s applied-hunk diff, survives a session replay). Keep UI-only data here, never in the model-facing `content`.
 - **Use `exec.agent` for async notifications.** `agent.inject(content, {source: {kind: 'plugin', plugin: '<name>'}})` appends durable context the NEXT model request sees — it is not a wake-up (an idle agent stays idle). Guard against disposed agents (try/catch).

 ## Long-running work
@@ -48,6 +49,26 @@ Follow tool-bash's background pattern: a `run_in_background` flag returns a task

 Prefer not to build policy into the tool. The seam is the `tools/execute` waterfall (veto or wrap — see the permission-gate example in [extension-cookbook.md](./extension-cookbook.md)), or a sandboxing implementation behind the tool's executor seam.

+## How your tool renders in an editor (ACP presentation)
+
+Your tool's `execute` returns model-facing content; its **editor card** is a separate, optional concern you declare with two pure display methods on the `defineTool` options. Design this alongside `execute`, not after — an editor (Zed, over the ACP bridge) shows the card, and a tool with no presentation falls back to a bland generic card (title = tool name, raw args as input).
+
+Both methods return a **`card`-tagged render intent** — pick the card kind that matches what your tool does:
+
+- `presentCall(args)` → a `ToolCallView` (the PENDING card):
+  - `{ card: 'generic', title, kind?, rawInput?, content?, locations? }` — the default. Set `kind` for an icon (`read`/`search`/…); set `locations: [{ path, line? }]` for any file your tool touches so a capable editor follows along / jumps to it.
+  - `{ card: 'terminal', title, description?, cwd? }` — your call IS a shell command. `title` is the command, `description` renders above the terminal card. (tool-bash.)
+  - `{ card: 'diff', title, diffs, locations? }` — your call creates or modifies a file. `diffs: [{ path, oldText, newText }]` (`oldText: null` for a new file) renders as an inline diff card. (tool-fs `write`/`edit`.)
+- `presentResult(args, { content, isError, meta? })` → a `ToolResultView` (the COMPLETED card): `{ card: 'generic', title?, content? }`, `{ card: 'terminal', title?, output?, exitCode?, signal? }` (the run's captured output + exit — the bridge shows an exit pill and derives a fenced ` ```console ` fallback for editors without the terminal capability), or `{ card: 'diff', title?, diffs }` (a completed file mutation — the applied hunks computed from the before/after content when there is a before-image, else a whole-file diff for a create; `write`/`edit` attach the hunks via the `meta` channel and read them back here). A mutation tool returns the `diff` result even when it duplicates the call-time card, because an ACP `tool_call_update.content` REPLACES the call's content — a non-diff result would clobber the pending diff. `result.meta` is your tool's own optional presentation payload, attached from `execute` (see below) and persisted so a replay reproduces the card.
+
+Hard rules (they bite if broken):
+
+- **Purity.** These run on live streaming AND on session-log REPLAY, so they must be pure functions of `args` (+ the result) — NO I/O, NO reading session state, NO clock/random. A diff is derived from the args (`write` uses `oldText: null` because a call-time presenter has no prior file content); the BRIDGE, not the tool, fills the session cwd and relativizes a display-path title. If you find yourself wanting the file's old content or the working directory inside `presentCall`, stop — that belongs on the bridge or a future result-event shape, not the presenter.
+- **UI-only formatting stays out of the model result.** A fenced ` ```console ` block, a diff, a relativized path — none of these may appear in what `execute` returns to the model; they live only in the presentation. (A `terminal` result view carries RAW `output`; the bridge adds the fences.)
+- **`defineTool` soft-validates the display path.** A malformed/older logged arg shape makes the wrapper return `undefined` (a generic fallback) rather than throw — display must never crash a replay.
+
+The neutral vocabulary lives in `dsh-tools` (never import an ACP type into a tool); the ACP bridge maps each `card` to the wire. The design and the why are in [the render-intent-union RFC](../rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md); `dsh-tool-fs` (generic/diff) and `dsh-tool-bash` (terminal) are the reference implementations.
+
 ## Tests every tool needs

-Arg-validation rejections, result shaping for every outcome, the HMR disposal test, and — for tools with side effects — an integration spec that drives the tool through the agent loop with a scripted `MockAdapter` (`packages/core/agent-loop/tests/mock-adapter.ts`), asserting the `tool/call` / `tool/result` session events.
+Arg-validation rejections, result shaping for every outcome, the HMR disposal test, and — for tools with side effects — an integration spec that drives the tool through the agent loop with a scripted `MockAdapter` (`packages/core/agent-loop/tests/mock-adapter.ts`), asserting the `tool/call` / `tool/result` session events. **If your tool has an editor card, also add:** a unit test on `presentCall`/`presentResult` asserting the exact view shape, AND — because a unit test proves the shape but not that an editor renders it — a **snapshot scenario** under `examples/acp-agent/tests/snapshots/` that drives the real tool through the ACP bridge and pins the rendered `tool_call` transcript (the card kind is only verified end-to-end there; see the [ACP snapshot-tests RFC](../rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md)). A tool whose card is a `terminal` needs a scenario whose `input.json` sets `terminalOutput: true` to exercise the capable-client `_meta` path.
--- a/docs/cordis-catalog/events-and-services.md
+++ b/docs/cordis-catalog/events-and-services.md
@@ -259,7 +259,7 @@ A session was created in the store.
 'session/created'(session: Session): void
 ```

-Source: [`packages/core/session/src/index.ts:34`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:35`](../../packages/core/session/src/index.ts)

 #### `session/event` — emit

@@ -271,7 +271,7 @@ An event was appended to a session log (sync, fire-and-forget). This is the per-

 Types: [SessionEvent](../core-data-structures/core.md)

-Source: [`packages/core/session/src/index.ts:40`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:41`](../../packages/core/session/src/index.ts)

 #### `session/flush` — parallel

@@ -281,7 +281,7 @@ Awaited durability checkpoint. The agent loop awaits `ctx.parallel('session/flus
 'session/flush'(session: Session): Promise<void> | void
 ```

-Source: [`packages/core/session/src/index.ts:49`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:50`](../../packages/core/session/src/index.ts)

 ### `subagent/*`

@@ -337,7 +337,7 @@ A tool was registered or unregistered (the available tool set changed).
 'tools/change'(): void
 ```

-Source: [`packages/core/tools/src/index.ts:48`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:66`](../../packages/core/tools/src/index.ts)

 #### `tools/execute` — waterfall

@@ -349,7 +349,7 @@ Waterfall around every tool execution — the single seam where sandbox, permiss

 Types: [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md)

-Source: [`packages/core/tools/src/index.ts:43`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:61`](../../packages/core/tools/src/index.ts)

 ### `web/*`

@@ -521,7 +521,7 @@ get(id: SessionId): Session | undefined
 list(): Session[]
 ```

-Source: [`packages/core/session/src/index.ts:322`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:323`](../../packages/core/session/src/index.ts)

 ### `ctx.subagents` — `SubagentService`

@@ -561,7 +561,7 @@ async execute(exec: ToolExecution): Promise<ToolExecutionResult>

 Types: [ToolDefinition](../core-data-structures/tools.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md)

-Source: [`packages/core/tools/src/index.ts:287`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:199`](../../packages/core/tools/src/index.ts)

 ### `ctx.web` — `WebService`

--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -11,7 +11,7 @@ Precisely, a data structure is **core** if either:
 1. it flows through the agent-loop spine — the loop holds it, derives it, streams it, or logs it on every turn (a `Message`, a `StreamChunk`, a `SessionEvent`, the `Agent` handle itself), independent of which plugins are present; **or**
 2. it is the single headline type a plugin author writes against a pipeline — `ToolDefinition` (what every tool *is*).

-Everything else is documented on a **sub-page**, not here. The rule that draws the line: *the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a sub-page detail.* So `ToolDefinition` is core, but the `SchemaSpec`/`InferArgs` DSL that types it, the `ToolCallPresentation` vocabulary that renders it, and the `SessionPersistence` seam that stores the event log are not — they live on the sub-pages below.
+Everything else is documented on a **sub-page**, not here. The rule that draws the line: *the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a sub-page detail.* So `ToolDefinition` is core, but the `SchemaSpec`/`InferArgs` DSL that types it, the `ToolCallView`/`ToolResultView` render-intent vocabulary that renders it, and the `SessionPersistence` seam that stores the event log are not — they live on the sub-pages below.

 | Sub-page | Owns |
 |---|---|
--- a/docs/core-data-structures/filesystem.md
+++ b/docs/core-data-structures/filesystem.md
@@ -64,6 +64,8 @@ type FsWriteIntent =
 interface FsWriteOutcome {
  operation: 'create' | 'update'
  version: FsVersion
+  before: string | null
+  after: string
 }
 ```

@@ -82,6 +84,8 @@ interface FsEditOutcome {
  replacements: number
  replaceAll: boolean
  version: FsVersion
+  before: string
+  after: string
 }
 ```

--- a/docs/core-data-structures/session.md
+++ b/docs/core-data-structures/session.md
@@ -32,7 +32,7 @@ interface SessionEventMap {
   */
  'assistant/message': { turn: number; step: number; content: ContentBlock[]; usage?: TokenUsage }
  'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string }
-  'tool/result': { turn: number; step: number; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string } }
+  'tool/result': { turn: number; step: number; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string }; meta?: unknown }
  /** Steering content injected between steps of a running turn. */
  'steering/message': { turn: number; content: ContentBlock[]; source: MessageSource }
  /**
--- a/docs/core-data-structures/tools.md
+++ b/docs/core-data-structures/tools.md
@@ -2,7 +2,7 @@

 The tool pipeline of [dsh-tools](../../packages/core/tools). [core.md](core.md) introduces `ToolDefinition` as the one pipeline-authoring type promoted to the spine and `ToolSchema` as the model-facing wire shape. This page owns the full `ToolDefinition`, the typed schema DSL that builds it, the waterfall execution shapes, and the UI-presentation vocabulary.

-Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts) · [`packages/core/tools/src/schema.ts`](../../packages/core/tools/src/schema.ts)
+Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts) · [`packages/core/tools/src/schema.ts`](../../packages/core/tools/src/schema.ts) · [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts)

 ## `ToolDefinition` — a registered tool

@@ -10,23 +10,25 @@ A `ToolSchema` (the model-facing fields) plus the `execute` function and optiona

 ```ts type-equiv
 interface ToolDefinition extends ToolSchema {
-  execute(args: unknown, exec: ToolExecution): Promise<ContentBlock[]>
+  execute(args: unknown, exec: ToolExecution): Promise<ToolExecuteReturn>
  /**
-   * Optional: how to present the PENDING state of one call in a UI, derived
-   * from the call's `args` (parsed arguments, `unknown` — the tool validates/
-   * narrows its own input). Returning `undefined` (or omitting the method) tells
-   * a UI to fall back to a generic presentation (title = tool name, raw args as
-   * input). Pure and side-effect-free: a UI may call it during live streaming
-   * AND a session-log replay, so it must depend only on `args`.
+   * Optional: how to present the PENDING state of one call in a UI, derived from
+   * the call's `args` (parsed arguments, `unknown` — the tool validates/narrows
+   * its own input). Returns a {@link ToolCallView} (a `card`-tagged render intent),
+   * or `undefined` (or omit the method) to fall back to a generic presentation
+   * (title = tool name, raw args as input). Pure and side-effect-free: a UI may
+   * call it during live streaming AND a session-log replay, so it must depend
+   * only on `args`.
   */
-  presentCall?(args: unknown): ToolCallPresentation | undefined
+  presentCall?(args: unknown): ToolCallView | undefined
  /**
   * Optional: how to present the COMPLETED state, given the same `args` and the
-   * `result` (`execute`'s content + whether it errored). Returning `undefined`
-   * (or omitting the method) tells a UI to keep the pending title and render the
-   * raw result content. Pure and side-effect-free for the same replay reason.
+   * `result` (`execute`'s content + whether it errored). Returns a
+   * {@link ToolResultView}, or `undefined` (or omit the method) to keep the
+   * pending title and render the raw result content. Pure and side-effect-free
+   * for the same replay reason.
   */
-  presentResult?(args: unknown, result: ToolResult): ToolResultPresentation | undefined
+  presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined
 }
 ```

@@ -98,6 +100,13 @@ interface ToolExecutionResult {
   * text in `content` is always present; this is extra structure for code.
   */
  error?: ToolErrorInfo
+  /**
+   * The tool-private presentation payload from a successful `execute` (the object
+   * return form). Threaded onto the `tool/result` session event and back into
+   * {@link ToolResult} for `presentResult`. Opaque (`unknown`); absent when the
+   * tool attached none or the call failed.
+   */
+  meta?: unknown
 }
 ```

@@ -105,8 +114,11 @@ A waterfall listener receives `(exec, next)`: call `next()` to proceed (possibly

 ## Tool-presentation UI vocabulary

-How a tool wants its call shown in a UI (an editor tool-call card, a CLI log line), provider-neutral so a tool describes itself without depending on any client protocol. `presentCall` returns a `ToolCallPresentation` (pending state: `title`, `kind`, `rawInput`, `content`, `locations` — `{ path, line? }[]` files the call reads/modifies, for editor follow-along — and optional `terminal`); `presentResult` returns a `ToolResultPresentation` (completed state: replacement `title`, reformatted `content`, terminal `output`/exit). `ToolCallKind` (`'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'`) picks an icon. A `ToolTerminal` asks a capable UI to render the call as a terminal card (cwd header, output, exit-status pill).
+How a tool wants its call shown in a UI (an editor tool-call card, a CLI log line), provider-neutral so a tool describes itself without depending on any client protocol. `presentCall`/`presentResult` return a **`card`-tagged render intent** — a discriminated union a UI bridge switches on:

-> These shapes carry a `FIXME(tool-presentation)` in source: they grew incrementally and the call-vs-result terminal split is muddy. Before more tools/UIs depend on them, they will be redesigned (a tagged union over card kinds) and pinned in an RFC, migrating `dsh-tool-bash` and the ACP bridge together. Treat the field-level shapes here as provisional; the source is authoritative.
+- `ToolCallView` (pending): `{ card: 'generic', title, kind?, rawInput?, content?, locations? }` (the default card; `locations` is `{ path, line? }[]` files the call reads/modifies, for editor follow-along), `{ card: 'terminal', title, description?, cwd? }` (a shell command → a terminal card), or `{ card: 'diff', title, diffs, locations? }` (a file create/modify → an inline diff card; `diffs` is `{ path, oldText, newText }[]`, `oldText: null` for a new file).
+- `ToolResultView` (completed): `{ card: 'generic', title?, content? }`, `{ card: 'terminal', title?, output?, exitCode?, signal? }` (the captured run output + exit; a capable UI shows an exit-status pill, an incapable one gets a fenced ` ```console ` fallback the bridge derives from `output`), or `{ card: 'diff', title?, diffs }` (a completed file mutation → the change to show, typically the applied hunks with context lines computed from the before/after content, or a whole-file diff when there is no before-image — e.g. a file create. A `tool_call_update`'s content REPLACES the call's content, so a mutation tool returns this even when it duplicates the call-time snippet, to keep the result from clobbering the diff with result text).

-The full presentation field docs live in [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts). The bash tool's own schemas (`bash`/`bash_output`/`bash_kill`) and the executor they drive are on [bash.md](bash.md).
+`ToolCallKind` (`'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'`) picks an icon on a generic card. `FileLocation` (`{ path, line? }`) and `FileDiff` (`{ path, oldText, newText }`) are the shared file-card vocabulary. The design is pinned in [the render-intent-union RFC](../rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md); the ACP bridge maps a `diff` card to a `{ type: 'diff' }` content block, a `terminal` card to the `_meta` terminal convention, and relativizes a file card's title against the session cwd.
+
+The full presentation field docs live in [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts). The bash tool's own schemas (`bash`/`bash_output`/`bash_kill`) and the executor they drive are on [bash.md](bash.md).
--- a/docs/development.i18n.yaml
+++ b/docs/development.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
+development.md: ce431d95c5dbb976d0c3ffa827af46ba608b400e
+development.zh.md: 36155ee2b93f2bc309ca1341cbed82c37e2759c9
--- a/docs/development.md
+++ b/docs/development.md
@@ -1,5 +1,7 @@
 # Development guide

+English | [中文](development.zh.md)
+
 This guide covers the local setup needed to work on DeepSeek Harness and understand the local hooks, daily checks, and CI gates.

 ## Prerequisites
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -0,0 +1,155 @@
+# 开发指南
+
+[English](development.md) | 中文
+
+本指南覆盖参与 DeepSeek Harness 开发所需的本地环境搭建，并帮助你理解本地钩子、日常检查与 CI 门禁。
+
+## 前置条件
+
+- Node.js 24 或更新版本。仓库声明 `node >=24`；CI 在 Node 24 和 26 上跑矩阵。
+- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中钉住 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，先运行 `corepack enable`。
+- Git。
+- 可选：一个 DeepSeek API key，用于 coding-agent 演示和真实 API 的 e2e 测试。
+
+## 首次搭建
+
+在仓库根目录安装依赖：
+
+```sh
+pnpm install
+```
+
+安装同时会运行根目录的 `postinstall` 脚本，它通过 `scripts/install-lefthook.mjs` 从仓库 dev 依赖安装 lefthook；该包装脚本使用 lefthook 经过评审的 `--force` 模式，使已存在 `core.hooksPath` 的关联 worktree 不会让正常的 `pnpm run …` 命令失败。
+
+如果因为依赖是从缓存恢复或 `postinstall` 被跳过而缺少钩子，手动安装：
+
+```sh
+pnpm exec lefthook install --force
+```
+
+新克隆后先跑一次类型检查：
+
+```sh
+pnpm run typecheck
+```
+
+这次首跑会构建 package/vendor 构建图，并跑根目录 no-emit `tsconfig.json` 图（覆盖 examples、tests 和 scripts）。根图使用同一份源码 `paths` 映射，但依赖 project references，因此 vendor 代码在它自己的 tsconfig 设置下被检查。
+
+如果准备从新克隆或新 worktree 推送，还要构建一次：
+
+```sh
+pnpm run build
+```
+
+`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件。
+
+## 环境变量
+
+真实的 DeepSeek 适配器和 coding-agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 读取凭证：
+
+```sh
+DEEPSEEK_API_KEY=sk-...
+DEEPSEEK_BASE_URL=https://... # optional
+```
+
+`DEEPSEEK_BASE_URL` 可选，默认为公开 API。绝不要提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。
+
+## Git 钩子
+
+lefthook 在 `lefthook.yml` 中配置，作为评审前的本地早期检查点：
+
+- `pre-commit` 运行对暂存文件的 ESLint 修复、`pnpm run typecheck` 和 vendor manifest 守卫。
+- `pre-push` 运行 `pnpm run test`、`pnpm run test:snapshot`、`pnpm run hygiene`、`pnpm run doc-sync` 和 `pnpm run verify-module-graph`。
+
+vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。编辑 vendor 代码前先看 `vendor/README.md`。
+
+这些钩子并不与 CI 完全一致。特别是：`pre-push` 跑不带覆盖率的单元测试，而 CI 跑 `pnpm run test:coverage`；CI 还会跑 echo-agent 和 built-bin 冒烟测试，并在 Node 24 和 26 上跑矩阵。
+
+## CI 门禁
+
+GitHub 工作流在每个 pull request 上运行这些门禁：
+
+- `pnpm install --frozen-lockfile`
+- `pnpm run constraints`
+- `pnpm run typecheck`
+- `pnpm run lint`
+- `pnpm run doc-sync`
+- `pnpm run verify-module-graph`
+- `pnpm run test:coverage`
+- `pnpm run test:snapshot`
+- `pnpm run build`
+- `pnpm run hygiene`
+- 一个 echo-agent 冒烟测试，检查演示的工具调用、工具结果和 JSONL 输出
+- built-bin 冒烟测试，用纯 `node` 运行发布产物 `lib/bin.js` 入口
+
+`pnpm run hygiene` 是 `pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types` 的本地简写；CI 还会把 `pnpm run constraints` 作为更早的快速失败步骤单独跑一次，然后在 `pnpm run build` 之后跑完整的 hygiene 脚本。
+
+## 日常命令
+
+在仓库根目录使用：
+
+```sh
+pnpm run test           # unit tests
+pnpm run test:coverage  # unit tests with per-file coverage gates
+pnpm run test:e2e       # real-API tests; self-skips without DEEPSEEK_API_KEY
+pnpm run typecheck      # build package/vendor outputs, then typecheck examples, tests, and scripts
+pnpm run lint           # eslint .
+pnpm run lint:fix       # eslint . --fix
+pnpm run doc-typecheck  # compile checked TypeScript snippets in Markdown docs
+pnpm run gen-cordis-catalog     # regenerate docs/cordis-catalog/events-and-services.md from source
+pnpm run verify-cordis-catalog  # fail if the cordis events/services catalog is stale
+pnpm run verify-md-wrap  # fail on hard-wrapped prose paragraphs in docs/README markdown
+pnpm run verify-type-equiv  # fail if a ```ts type-equiv doc block drifts from its source type
+pnpm run doc-sync       # doc-typecheck, cordis-catalog freshness, markdown wrap/link, and type-equiv verification
+pnpm run gen-module-graph     # regenerate docs/module-graph.md from package peerDeps
+pnpm run verify-module-graph  # fail if docs/module-graph.md is stale
+pnpm run build          # emit lib/types intermediates, then bundle lib/index.* runtime files
+pnpm run verify-node-next-types  # fail if built declarations are not NodeNext-consumable
+pnpm run hygiene        # knip, publint, workspace constraints, and NodeNext declaration check
+```
+
+改动 package 的公开行为时，在同一个变更里更新相关 README 或 JSDoc。`pnpm run doc-sync` 能抓住被检查的 TypeScript 片段、cordis 事件/服务目录漂移和硬折行的 markdown 段落，但更广泛的行文/API 同步仍需评审把关。
+
+## 演示
+
+echo 演示不需要 API 凭证：
+
+```sh
+pnpm run demo:echo
+```
+
+coding-agent 演示使用真实的 DeepSeek 适配器，需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：
+
+```sh
+pnpm run demo:coding
+```
+
+ACP 服务器演示把同一个编码 agent（智能体）通过 JSON-RPC stdio 暴露出来，同样需要 `DEEPSEEK_API_KEY`：
+
+```sh
+pnpm run demo:acp
+```
+
+## TODO 标记
+
+用三种注释标签之一标记代码中的已知问题，按紧急程度排序：
+
+- `FIXME`——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 `FIXME` 出门。
+- `TODO`——应当尽快修复的问题，等资源到位就处理。
+- `XXX`——也许某天会修的问题；优先级最低，不作承诺。
+
+选择与紧急程度匹配的标签，让扫代码的人一眼分清「发布阻塞」和「有空再说」。
+
+## 逐字记录类型（`ts type-equiv`）
+
+[核心数据结构](core-data-structures/core.md)文档粘贴真实的类型定义，让读者看到确切的形状。为防止粘贴内容在源码变化时漂移，把它围栏成 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
+
+```json
+{ "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
+```
+
+`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明，并断言文档块与之一致（对空白和注释不敏感，因此文档块可以展示干净的定义，语义由行文承载）。它还强制 1:1 对应：每个 `ts type-equiv` 块恰好有一条 manifest 条目，反之亦然，因此不会有块被静默漏检，也不会有陈旧条目滞留。`doc-typecheck` 跳过 `ts type-equiv` 块（它们不能独立编译），并将其排除在 opt-out 比例之外。当你改动一个被记录的类型，门禁会失败直到你更新粘贴内容；当你增删一个块，在同一个变更里更新 manifest。
+
+## 架构上下文
+
+改动 `packages/` 下的任何东西之前先读 `docs/architecture.md`。这套代码围绕 Cordis 插件、事件溯源的会话、类型化的服务 seam（扩展点）与显式扩展点构建。
--- a/docs/i18n/README.i18n.yaml
+++ b/docs/i18n/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
+README.md: 6e2bbd27c3288037bafeb6cc71b801d56b956ab4
+README.zh.md: 04c99ae336cf1e96cbc185f0ccbd063ef8977944
--- a/docs/i18n/README.md
+++ b/docs/i18n/README.md
@@ -0,0 +1,50 @@
+# Bilingual documentation
+
+English | [中文](README.zh.md)
+
+This repo's documentation is read by people and agents both inside and outside the company, so the README and the docs tree are maintained in English and Simplified Chinese. This page defines the pairing contract, the enforcement gate, and the rollout policy; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).
+
+## The pairing contract
+
+- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first RFC is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.
+- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.
+- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:
+
+  ```yaml
+  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b
+  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b
+  ```
+
+  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. The recorded hash also recovers the exact last-confirmed text of either side (`git cat-file -p <hash>`), so an out-of-sync pair is updated by diffing the edited side against its last-confirmed state and patching the counterpart minimally — never by re-translating whole files. After bringing the pair back in line, `pnpm run verify-translation-pairing --write` re-records both hashes; that yaml diff is the reviewable act of confirming consistency.
+- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.
+- **Structure mirrors the counterpart.** Heading depths and order, list kinds, table columns, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).
+
+## The gate: verify-translation-pairing
+
+`pnpm run verify-translation-pairing` (part of `doc-sync`, so CI and the pre-push hook run it) enforces the contract mechanically:
+
+1. Every file listed as `required` in [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) has a complete pair.
+2. Every pair that exists at all — required or not — is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table column counts, list kinds, and every link target apart from the switcher.
+3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all.
+
+`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok — and is the work list for translation batches. It never fails; it reports.
+
+The practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.
+
+The gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.
+
+## Scope, exclusions, and rollout
+
+**Scope**: the root `README.md` and everything under `docs/**`. Package READMEs (`packages/**`) join the scope in a later batch.
+
+**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):
+
+- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/module-graph.md` — generated files; their generators emit English only today, so a hand-written translation would go stale on every regeneration. The planned follow-up is to teach the generators to emit Chinese alongside English, at which point these leave the exclusion list.
+- `docs/AGENTS.md` — agent instructions, maintained in English only like the root `AGENTS.md`.
+- `docs/i18n/terminology.md` — the terminology table is itself bilingual by construction.
+
+**Rollout**: the `required` list in the manifest is the enforcement frontier, not the goal. The goal is full bilingual coverage of the scope. Pairs land in reviewable batches (core entry docs, cookbook, RFCs, postmortems, …); each merged batch adds its files to `required`, so the gate ratchets forward and never regresses. Documents not yet in `required` are backlog — visible in `--list` — but any pair that already exists is held to the full contract regardless of the list. Pairing a document is a commitment: every later edit to either side must carry the counterpart along, so grow the frontier at the pace translation review is actually resourced, not ahead of it.
+
+## Division of labor
+
+Counterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate exists so that neither the agent nor the reviewer has to remember the contract: pair completeness, consistency, and structure are checked mechanically, and review attention goes to translation quality and terminology, where human judgment is the whole point.
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -0,0 +1,50 @@
+# 双语文档
+
+[English](README.md) | 中文
+
+本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此 README 与 docs 目录树以英文和简体中文双语维护。本页定义配对契约、强制门禁与推进策略；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。进仓的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。
+
+## 配对契约
+
+- **两种语言同权。**一篇文档可以先用任一语言撰写和评审——先写中文的 RFC 与先写英文的一样正当——另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。
+- **一对文档是三个同目录文件。**英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对整体合入：PR 永远不会只带一种语言而缺其余两个文件。
+- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：
+
+  ```yaml
+  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b
+  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b
+  ```
+
+  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。记录的 hash 还能还原任一侧上次确认时的确切文本（`git cat-file -p <hash>`），所以失去同步的配对是「把被改的一侧与其上次确认状态做 diff、再最小化地修补另一侧」——从不整篇重译。两侧对齐后，`pnpm run verify-translation-pairing --write` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审。
+- **语言切换行。**两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。
+- **结构与另一侧一一对应。**标题深度与顺序、列表类型、表格列、链接目标与逐字节一致的代码块在配对两侧一一对应——完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。
+
+## 门禁：verify-translation-pairing
+
+`pnpm run verify-translation-pairing`（`doc-sync` 的一环，因此 CI 和 pre-push 钩子都会运行）机械地强制执行这份契约：
+
+1. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 中 `required` 列出的每个文件都有完整配对。
+2. 任何已存在的配对——无论是否 required——都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致——标题深度、逐字节一致的代码块（信息字符串与内容）、表格列数、列表类型，以及除切换行之外的每个链接目标。
+3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。
+
+`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态——missing、out-of-sync 或 ok——是翻译批次的工作清单。它从不失败；它只报告。
+
+这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write`），与本仓库既有的代码/README doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。
+
+把门禁的边界说白：**门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。**它检查 hash 和形状；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然——那是契约中评审者的那一半，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。
+
+## 范围、排除与推进
+
+**范围**：根 `README.md` 与 `docs/**` 下的全部内容。package README（`packages/**`）在后续批次加入范围。
+
+**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：
+
+- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/module-graph.md`——生成文件；生成器目前只输出英文，手写译文在每次重新生成时必然陈旧。计划中的后续工作是让生成器同时输出中文，届时这些文件移出排除清单。
+- `docs/AGENTS.md`——agent 指令，与根 `AGENTS.md` 一样只以英文维护。
+- `docs/i18n/terminology.md`——术语表本身即是双语构造。
+
+**推进**：manifest 中的 `required` 列表是强制边界，不是目标。目标是范围内的全量双语覆盖。配对按可评审的批次落地（核心入口文档、cookbook、RFC、postmortem……）；每个批次合入后把其文件加进 `required`，门禁只进不退。尚未进入 `required` 的文档是 backlog——在 `--list` 中可见——但任何已存在的配对无论在不在清单里都按完整契约检查。给一篇文档配对是一份承诺：此后对任一侧的每次修改都必须带上另一侧，所以边界的扩张要跟上翻译评审的实际投入节奏，不要抢在前面。
+
+## 分工
+
+这里的对侧译文由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 产出、由人评审——在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁的存在让 agent 和评审者都不必记住契约：配对完整性、一致性和结构由机械检查兜底，评审注意力投向翻译质量与术语——这正是人的判断的用武之地。
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -7,6 +7,7 @@
 | ACP | ACP | 首次出现可写：ACP（Agent Client Protocol） |
 | AI | AI | 首次出现可写：人工智能（AI） |
 | API | API | |
+| CI | CI | |
 | CLI | CLI | 首次出现可写：命令行界面（CLI） |
 | Cordis | Cordis | 保留英文 |
 | Function Calling | Function Calling | 首次出现可写：Function Calling（函数调用） |
@@ -17,16 +18,22 @@
 | loader | loader | |
 | LLM | LLM | 首次出现可写：大语言模型（LLM） |
 | MCP | MCP | |
+| PR | PR | 首次出现可写：PR（pull request） |
 | RAG | RAG | 首次出现可写：检索增强生成（RAG） |
 | SDK | SDK | |
 | SSE | SSE | 首次出现可写：SSE（Server-Sent Events） |
 | agent | agent | 首次出现可写：agent（智能体） |
 | agent loop | agent loop | |
+| backlog | backlog | 双语翻译语境指待翻清单 |
+| blob hash | blob hash | git 对象哈希；`git hash-object` 的结果 |
+| doc-sync | doc-sync | 仓库门禁名，保留英文 |
+| e2e | e2e | |
 | fiber | fiber | 首次出现可写：fiber（插件运行时） |
 | fixture | fixture | 指测试前置数据或环境 |
 | fork | fork | 保留英文 |
 | harness | harness | 保留英文 |
 | manifest | manifest | 描述模块或工具元数据的文件 |
+| monorepo | monorepo | |
 | schema DSL | schema DSL | |
 | schema | schema | 保留英文 |
 | seam | seam | 首次出现可写：seam（扩展点） |
@@ -36,6 +43,7 @@
 | subagent | subagent | 首次出现可写：subagent（子 agent） |
 | transcript | transcript | 首次出现可写：transcript（文本记录）；指会话渲染给用户或编辑器的完整文本，区别于事件日志（event log） |
 | waterfall | waterfall | 首次出现可写：waterfall（瀑布式事件） |
+| worktree | worktree | git 工作区概念，保留英文 |
 | wire format | 协议格式 | 首次出现可写：协议格式（wire format） |
 | adapter contract | 适配器契约 | 首次出现可写：适配器契约（adapter contract） |
 | adapter | 适配器 | |
@@ -54,28 +62,39 @@
 | config | 配置 | |
 | context | 上下文 | |
 | context compaction | 上下文压缩 | 首次出现可写：上下文压缩（context compaction） |
+| contract | 契约 | 如：配对契约（pairing contract）；另见 adapter contract |
 | coverage | 覆盖率 | |
 | crash recovery | 崩溃恢复 | |
 | dispose | dispose | 首次出现可写：dispose（释放资源）；正文优先保留英文 |
 | durability | 持久性 | |
+| enforcement frontier | 强制边界 | i18n 机制词：manifest `required` 清单所划的门禁生效范围 |
 | event log | 事件日志 | |
 | event | 事件 | |
 | event stream | 事件流 | |
+| event-sourced | 事件溯源 | DDD 社区通行译法 |
 | executor | 执行器 | |
 | extension | 扩展 | |
+| fail-fast | 快速失败 | |
+| fenced code block | 围栏代码块 | MDN 中文同译 |
 | finish reason | 结束原因 | |
+| fingerprint | 指纹 | i18n 机制词：`.zh.md` 首行记录英文源 blob hash 的 `i18n-source` 注释 |
 | foreground run | 前台运行 | |
+| freshness | 新鲜度 | MDN HTTP 缓存中文同译（freshness lifetime → 新鲜度生命周期）；指译文相对英文源的同步状态 |
 | hook | 钩子 | |
 | implementation | 实现 | |
 | inference | 推理（inference） | 每次提及时保留英文括注，避免与 reasoning 混淆 |
+| info string | 信息字符串 | CommonMark 中文同译；代码围栏 ``` 之后的语言标注 |
 | injection | 注入 | |
 | interface | 接口 | |
 | integration | 集成 | |
+| language switcher | 语言切换行 | i18n 机制词：双语配对文件顶部的互链行 |
 | memory | memory / 记忆 / 内存 | 按上下文区分：agent memory 译为“记忆”；resource/memory usage 译为“内存” |
 | message | 消息 | |
 | mod | 模组 | 区别于 module（模块）；plugin 译作「插件」 |
 | model provider | 模型提供方 | |
 | module | 模块 | |
+| orphan | 孤立 | git 官方中文同译（如「孤立分支」）；指英文源已不存在的 `.zh.md`；不要译作：孤儿 |
+| pairing | 配对 | |
 | permission | 权限 | |
 | persistence | 持久化 | |
 | pipeline | 流水线 | |
@@ -93,11 +112,15 @@
 | service | 服务 | |
 | session | 会话 | |
 | session event | 会话事件 | |
+| smoke test | 冒烟测试 | |
 | snapshot | 快照 | |
 | spine | 主干 | |
+| staged | 暂存 | git 官方中文同译 |
+| stale | 陈旧 | MDN HTTP 缓存中文同译，与「新鲜（fresh）」成对；门禁输出保留英文 `stale`；expired 才译「过期」 |
 | step | 步骤 | |
 | stream | 流 | |
 | streaming | 流式输出 | |
+| structural signature | 结构签名 | i18n 机制词：配对门禁比对的有序结构序列 |
 | system prompt | 系统提示词 | |
 | taxonomy | 分类体系 | |
 | token usage | token 用量 | |
--- a/docs/i18n/translation-rules.i18n.yaml
+++ b/docs/i18n/translation-rules.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
+translation-rules.md: 4e190f58469f7d402dfa5600f17cf1621484f138
+translation-rules.zh.md: 89a1cddd23126f24354ce1f8d9af4e7bd403454d
--- a/docs/i18n/translation-rules.md
+++ b/docs/i18n/translation-rules.md
@@ -0,0 +1,60 @@
+# Translation rules
+
+English | [中文](translation-rules.zh.md)
+
+How to translate between the two sides of a documentation pair in this repo. Both languages carry equal authority ([README.md](README.md)): a change is authored in either language, and that side is the source for that update — these rules govern producing or updating the counterpart. They bind humans and agents equally; the committed agent workflow that applies them is [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md). Rule levels follow RFC 2119 usage: **MUST** / **MUST NOT** are gate- or review-blocking; **SHOULD** needs a stated reason to deviate; **MAY** is discretionary.
+
+## Faithfulness
+
+- The counterpart MUST say what the authored side says — no added behavior, prerequisites, warnings, version claims, or examples, and no dropped ones. If the pair disagrees on substance, neither language wins by default: fix the side that is wrong, then bring the other along in the same change.
+- The counterpart SHOULD read as natural technical writing in its own language, not word-by-word gloss. Translate meaning, restructure sentences where the target grammar wants it, and keep the author's register — terse stays terse.
+- Do not translate the untranslatable: if a sentence resists natural rendering because it leans on an idiom of the source language, translate the idea, not the idiom.
+
+## Structure preservation
+
+The paired files MUST match one to one in:
+
+- heading hierarchy (same levels, same order — heading TEXT is translated),
+- list shape and numbering,
+- tables (same columns, same row order; header cells translated per terminology),
+- fenced code blocks — **byte-identical, including comments**; code is part of the verified surface (` ```ts ` blocks compile under `doc-typecheck`), and an edited comment is drift the fence-count gate cannot see,
+- inline code spans (commands, flags, config keys, file paths, event names, API names, version numbers) — verbatim, never translated or reformatted,
+- links and anchors: every relative link MUST point at the same target in both files — by convention the `.md` path, not the `.zh.md` sibling — so links never dangle when one pair lands before its neighbors. The ONLY zh-specific link is the language switcher. Link TEXT is translated; the target is not.
+
+The repo's Markdown conventions apply to `.zh.md` files unchanged: one physical line per paragraph (`verify-md-wrap`), resolving relative links (`verify-md-links`), exactly one trailing newline.
+
+## Terminology
+
+- [terminology.md](terminology.md) is the source of truth in both directions. Before translating, load it; while translating, every term it lists MUST be rendered exactly as it specifies, including its first-occurrence annotations (e.g. `agent（智能体）` on first mention, plain `agent` after) and its "不要译作" prohibitions. When the Chinese side is authored first, the English counterpart uses the table's English column the same way.
+- A technical term NOT in the table MAY be translated only when a major Chinese-language OSS or vendor doc has an established rendering for it (K8s/Vue/MDN Chinese docs, 微软简中风格指南, big-tech project docs). Cite the precedent in the PR.
+- A term with NO established precedent MUST stay in English in the translation and MUST be listed in the PR description under 「待定术语」(pending terms) with a suggested rendering for the reviewer to decide. MUST NOT invent a Chinese rendering inline — an unprecedented translation creates exactly the ambiguity the terminology table exists to prevent. Decided terms then land in [terminology.md](terminology.md) in the same PR or a follow-up.
+
+## Typography
+
+These rules govern the Chinese side; the English side follows the repo's normal Markdown conventions (root `AGENTS.md`). The mixed-script rules below follow the cross-project consensus of the [MDN Simplified Chinese translation guide](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md), the [Kubernetes zh-cn localization guide](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/), the [Vue.js Chinese translation conventions](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5), and [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines), which in turn ground in [W3C clreq](https://www.w3.org/TR/clreq/) and GB/T 15834—2011:
+
+- MUST put one half-width space between Chinese text and Latin words, and between Chinese text and numerals: `每个 plugin 注册 3 个 tool`。No space between a full-width punctuation mark and anything.
+- MUST use full-width (Chinese) punctuation in Chinese prose: `，。：；？！（）「」`. Half-width punctuation stays inside code spans, inside complete English sentences quoted as-is, and in numbers (`3.5`, `1,024`).
+- Enumeration commas: a Chinese list of parallel items uses 顿号（、）, not commas.
+- MUST NOT use full-width digits or full-width Latin letters — `１２３` never, `123` always.
+- Proper nouns keep their canonical casing: GitHub, TypeScript, DeepSeek — never `github`/`Github` unless quoting code.
+- Second person is 你, not 您 (matches the Vue and Kubernetes Chinese conventions and this repo's direct voice).
+- Emphasis markers (`**bold**`, `*italic*`) stay on the same spans as the source; Chinese has no italics, so the rendered emphasis may look identical — do not substitute quotation marks or other decoration.
+
+## Quality bar
+
+- A pair is done when a bilingual engineer reading either file alone gets everything a reader of the other gets — same facts, same caveats, same tone — and nothing extra.
+- Before handing off, self-check the result against this file and re-read the counterpart ALONE, without the source side by side; awkward phrasing is easier to hear without the source anchoring you.
+- The mechanical contract (consistency record, switcher, structure, wrap, links) is checked by `pnpm run verify-translation-pairing` and the rest of `doc-sync` — run them; do not hand-verify what a gate covers.
+
+## References
+
+Authorities cited by these rules, for humans and agents who want the underlying reasoning:
+
+- [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines) — the de-facto community standard for mixed CJK/Latin spacing and punctuation.
+- [MDN zh-CN translation guide](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md) — an in-repo translation-rules file of the same shape as this one; spacing, punctuation, and glossary practice.
+- [Kubernetes zh-cn localization guide](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/) — terminology-first-occurrence and punctuation practice from the largest zh localization team.
+- [Vue.js docs-zh-cn 翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5) — per-term translate/keep decisions and tone.
+- [zh-style-guide](https://zh-style-guide.readthedocs.io) — a community Chinese technical-writing style guide whose rule-level taxonomy (and RFC 2119 keyword levels) this file borrows; aggregates GB/T 15834/15835, clreq, and vendor guides.
+- [W3C clreq](https://www.w3.org/TR/clreq/) and the [Microsoft Simplified Chinese style guide](https://learn.microsoft.com/en-us/globalization/reference/microsoft-style-guides) — the formal typographic and vendor-localization baselines.
+- GB/T 19682-2005《翻译服务译文质量要求》 — the national standard whose three base requirements (忠实原文、术语统一、行文通顺) this file's Faithfulness and Terminology sections operationalize.
--- a/docs/i18n/translation-rules.zh.md
+++ b/docs/i18n/translation-rules.zh.md
@@ -0,0 +1,60 @@
+# 翻译规则
+
+[English](translation-rules.md) | 中文
+
+本文规定如何在本仓库文档配对的两侧之间进行翻译。两种语言同权（见 [README.md](README.md)）：一次变更用任一语言撰写，那一侧就是这次更新的源——本文的规则约束的是产出或更新另一侧。这些规则对人和 agent（智能体）同等生效；应用它们的进仓 agent 工作流是 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。规则级别沿用 RFC 2119 的用法：**必须（MUST）**／**禁止（MUST NOT）**会卡门禁或评审；**应当（SHOULD）**偏离时要说明理由；**可以（MAY）**自行裁量。
+
+## 忠实性
+
+- 另一侧必须说撰写侧所说的话——不添加行为、前置条件、警告、版本声明或示例，也不丢弃任何一项。如果两侧在实质内容上不一致，没有哪种语言默认获胜：改正错的那一侧，并在同一个变更里把另一侧带上。
+- 另一侧应当读起来是其语言自然的技术文字，而不是逐词对照。翻译语义，在目标语言语法需要处重组句子，并保持原作者的语域——简练的保持简练。
+- 不要翻译不可译的东西：一句话如果依赖源语言的习语而无法自然转换，就翻译它的意思，而不是习语本身。
+
+## 结构保持
+
+配对的两个文件必须在以下方面一一对应：
+
+- 标题层级（相同级别、相同顺序——标题的**文字**要翻译），
+- 列表形态与编号，
+- 表格（相同的列、相同的行序；表头单元格按术语表翻译），
+- 围栏代码块——**逐字节一致，包括注释**；代码属于受验证的范围（` ```ts ` 块要通过 `doc-typecheck` 编译），而被改动的注释是代码块计数门禁看不见的漂移，
+- 行内代码（命令、flag、配置键、文件路径、事件名、API 名、版本号）——原样保留，从不翻译或重排，
+- 链接与锚点：每个相对链接在两个文件中必须指向相同的目标——按约定是 `.md` 路径而非 `.zh.md` 兄弟文件——这样某对文档先于相邻文件落地时，链接也永不悬空。唯一的 zh 特有链接是语言切换行。链接**文字**翻译；链接目标不翻。
+
+本仓库的 Markdown 约定对 `.zh.md` 文件原样生效：一个段落一个物理行（`verify-md-wrap`）、相对链接必须可解析（`verify-md-links`）、文件末尾恰好一个换行。
+
+## 术语
+
+- [terminology.md](terminology.md) 是双向的术语真源。翻译前先加载它；翻译中，表内的每个术语都必须严格按表规定的译法呈现，包括首次出现的括注（如首现写 `agent（智能体）`，之后写 `agent`）与「不要译作」的禁项。中文先行撰写时，英文另一侧同样按表中英文列使用术语。
+- 表中**没有**的技术术语，只有当某个主要中文 OSS 或厂商文档已有成型译法时（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档）才可以翻译。在 PR 中注明先例出处。
+- **没有**成型先例的术语，译文中必须保留英文，并且必须在 PR 描述的「待定术语」下列出、附上建议译法交评审者定夺。禁止就地发明中文译法——无先例的翻译恰恰制造了术语表要防止的歧义。定下来的术语随后在同一个 PR 或后续 PR 进入 [terminology.md](terminology.md)。
+
+## 排版
+
+本节规则约束中文一侧；英文一侧遵循仓库常规的 Markdown 约定（根 `AGENTS.md`）。下面的中西文混排规则遵循 [MDN 简体中文翻译指南](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md)、[Kubernetes 中文本地化指南](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/)、[Vue.js 中文翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5)与[中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)的跨项目共识，其根据是 [W3C clreq](https://www.w3.org/TR/clreq/) 与 GB/T 15834—2011：
+
+- 必须在中文与拉丁词之间、中文与数字之间各留一个半角空格：`每个 plugin 注册 3 个 tool`。全角标点与任何字符之间不加空格。
+- 中文行文必须使用全角（中文）标点：`，。：；？！（）「」`。半角标点保留在代码内、按原样引用的完整英文句子内、以及数字内（`3.5`、`1,024`）。
+- 并列顿开：中文的并列项之间用顿号（、），不用逗号。
+- 禁止使用全角数字或全角拉丁字母——永远不写 `１２３`，永远写 `123`。
+- 专有名词保持规范大小写：GitHub、TypeScript、DeepSeek——除非引用代码，否则绝不写 `github`／`Github`。
+- 第二人称用「你」，不用「您」（与 Vue、Kubernetes 中文约定及本仓库的直接语气一致）。
+- 强调标记（`**加粗**`、`*斜体*`）落在与另一侧相同的文字段上；中文没有斜体，渲染效果可能看不出差别——不要用引号或其他装饰替代。
+
+## 质量线
+
+- 一对文档的完成标准：一位双语工程师只读其中任一文件，得到与另一文件读者完全相同的信息——相同的事实、相同的告诫、相同的语气——并且没有任何多余的内容。
+- 交付前，对照本文自查一遍，并**只读另一侧**再通读一遍、不看源侧对照；没有源文锚着，别扭的表述更容易被听出来。
+- 机械契约（一致性记录、切换行、结构、折行、链接）由 `pnpm run verify-translation-pairing` 和 `doc-sync` 的其余门禁检查——跑门禁；门禁覆盖的不要手工核对。
+
+## 参考资料
+
+本文各规则引用的权威出处，供想了解底层依据的人和 agent 查阅：
+
+- [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)——中西文混排空格与标点的社区事实标准。
+- [MDN 简体中文翻译指南](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md)——与本文同形态的进仓翻译规则文件；空格、标点与术语表实践。
+- [Kubernetes 中文本地化指南](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/)——最大的中文本地化团队的术语首现与标点实践。
+- [Vue.js docs-zh-cn 翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5)——逐术语的译／留决策与语气。
+- [zh-style-guide](https://zh-style-guide.readthedocs.io)——社区中文技术文档写作规范，本文借用了它的规则级别分类体系（与 RFC 2119 关键词分级）；它聚合了 GB/T 15834/15835、clreq 与各厂商指南。
+- [W3C clreq](https://www.w3.org/TR/clreq/) 与[微软简体中文风格指南](https://learn.microsoft.com/en-us/globalization/reference/microsoft-style-guides)——排版学与厂商本地化的正式基线。
+- GB/T 19682-2005《翻译服务译文质量要求》——国家标准；本文「忠实性」与「术语」两节把它的三项基本要求（忠实原文、术语统一、行文通顺）落成可操作规则。
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -69,6 +69,7 @@ graph TD
  tool-bash --> tools
  tool-fs --> fs
  tool-fs --> llm
+  tool-fs --> session
  tool-fs --> system-prompt
  tool-fs --> tools
  tool-todo --> agent
@@ -148,7 +149,7 @@ graph TD
 | `agent-loop` | `agent`, `llm`, `session`, `session-persistence`, `system-prompt`, `tools` |
 | `subagent` | `agent`, `llm`, `tools` |
 | `tool-bash` | `agent`, `bash`, `llm`, `tools` |
-| `tool-fs` | `fs`, `llm`, `system-prompt`, `tools` |
+| `tool-fs` | `fs`, `llm`, `session`, `system-prompt`, `tools` |
 | `tool-todo` | `agent`, `session`, `tools` |
 | `tool-web` | `llm`, `system-prompt`, `tools`, `web` |
 | `agent-core` | `agent`, `agent-loop`, `invariants`, `llm`, `session`, `system-prompt`, `tool-bash`, `tools` |
--- a/docs/rfc/README.md
+++ b/docs/rfc/README.md
@@ -126,6 +126,8 @@ Do NOT write one for a mechanical or local choice (a variable name, a one-file r
 | [Web capability seam — provider registry and model-facing web tools](implemented/architecture/2026-06-24-web-capability-seam.md) | 2026-06-24 |
 | [Make `dsh-fs-policy` an event-gate plugin, not a method interface](implemented/architecture/2026-06-26-file-context-as-event-gate.md) | 2026-06-26 |
 | [Resolve filesystem paths against the caller's session cwd](implemented/architecture/2026-07-02-fs-per-session-cwd.md) | 2026-07-02 |
+| [Tagged render-intent union for tool-call presentation](implemented/architecture/2026-07-02-tool-render-intent-union.md) | 2026-07-02 |
+| [Result-time applied-hunk diffs for file mutations](implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.md) | 2026-07-02 |
 | [Add direct directory listing to the filesystem seam](implemented/architecture/2026-07-03-filesystem-directory-listing-seam.md) | 2026-07-03 |

 ### Process
@@ -143,6 +145,7 @@ Do NOT write one for a mechanical or local choice (a variable name, a one-file r
 | [Generated cordis events + services catalog](implemented/process/2026-06-20-generated-cordis-catalog.md) | 2026-06-20 |
 | [Classify RFCs by kind via path-encoded subdirectories](implemented/process/2026-06-20-rfc-classification.md) | 2026-06-20 |
 | [Generated tool-schema catalog (boot-and-harvest)](implemented/process/2026-07-02-tool-schema-catalog.md) | 2026-07-02 |
+| [Bilingual documentation via paired sibling files and a pairing gate](implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md) | 2026-07-02 |

 ### Testing

--- a/docs/rfc/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.md
+++ b/docs/rfc/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.md
@@ -0,0 +1,55 @@
+# RFC: Result-time applied-hunk diffs for file mutations
+
+Status: implemented
+
+## Problem
+
+The [tagged render-intent union](2026-07-02-tool-render-intent-union.md) gave `dsh-tool-fs` write/edit a `card:'diff'` at CALL time, derived purely from the tool's args: write ⇒ `{oldText:null, newText:content}` (the whole new file), edit ⇒ `{oldText:old_string, newText:new_string}` (the bare replaced snippet). An editor renders that as an inline diff, but it is a **context-free** diff — the bare `old_string`→`new_string` with no surrounding lines, and a `replace_all` that touched five scattered sites still renders as one snippet pair.
+
+Driving `claude-agent-acp`'s own ACP bridge shows what a full editor diff looks like: after the mutation applies, it emits a SECOND `tool_call_update` whose diff is the **applied hunk with ±3 context lines** (and one hunk per changed site for `replace_all`), reconstructed from the tool's `structuredPatch`. That result-time hunk is what makes Zed show the change *in place* in the file rather than as a floating snippet. Our tools stopped at the call-time snippet; the completed result carried only the plain "updated successfully" text, no diff.
+
+The obstacle is a seam boundary: `presentResult(args, result)` is a **pure function of `args` + the model-facing `result` (`{content, isError}`)** — it runs on live streaming AND on session-log replay, so it must be replay-deterministic and cannot do I/O. It never sees the file's before/after content, and `FsEditOutcome`/`FsWriteOutcome` carried only a replacement count + version, not the text. So there was no way to compute — or even carry — an applied hunk to the presenter.
+
+## Decision
+
+Add a **persisted, tool-private presentation channel** so a tool's `execute` can attach a result-time render payload that survives replay, and use it to carry the applied-hunk diff.
+
+### 1. A `meta` channel on the tool result (core)
+
+`ToolDefinition.execute` may now return either its model-facing `ContentBlock[]` (unchanged, the common case) OR `{ content: ContentBlock[]; meta?: unknown }`:
+
+```ts ignore-check
+type ToolExecuteReturn = ContentBlock[] | { content: ContentBlock[]; meta?: unknown }
+```
+
+`meta` is an opaque payload the core never interprets — typed `unknown` at every seam (the tool that produced it owns and narrows its shape). It MUST be JSON-serializable: the registry threads it onto the `tool/result` **session event**, and `Session.append` runtime-validates all event data with the existing `isJsonValue` predicate, so a non-serializable `meta` is rejected at the source. On replay the same `meta` is read back and handed to `presentResult` via a widened `ToolResult` (`{ content, isError, meta? }`). Because the payload lives in the event log, the diff reproduces on session reload / snapshot replay **for free** — the event-sourcing guarantee, not a re-computation. Typing `meta` as `unknown` (rather than a shared serializable-value type) keeps the tools core free of a dependency it would otherwise take just to name the type, and the runtime `isJsonValue` gate — not the static type — is what actually enforces serializability.
+
+This is the general shape ("a tool attaches durable result presentation"), not an fs-specific one — any tool can use it.
+
+### 2. The tool computes the hunk; the backend returns before/after (fs)
+
+Per the [capability-seam split](2026-06-13-capability-seams.md), the storage backend returns only **storage facts** and the model-facing tool owns **presentation**:
+
+- `dsh-fs` widens `FsEditOutcome` with `{ before: string; after: string }` and `FsWriteOutcome` with `{ before: string | null; after: string }` (`before: null` ⇒ a create, or an existing-but-undiffable binary/non-UTF-8 file). The local backend already holds both texts at write time; it returns them as raw LF-normalized text, with **no diff/UI concept** entering the seam.
+- `dsh-tool-fs` computes the contextual hunk from before/after and attaches it as `meta: { diffs: FileDiff[] }`. A contextual hunk is computed only when a before-version exists — edit always; write on overwrite; a create has no before, matching `claude-agent-acp`'s empty `structuredPatch` on create. But the completed `tool_call_update` is ALWAYS a `diff` card for a successful mutation: an ACP `tool_call_update.content` REPLACES the call's content, so rendering the model-facing result text would clobber the pending diff. So `write`'s result falls back to an args-derived whole-file diff (`oldText: null`) when it has no contextual hunk (a create, or an overwrite whose content is unchanged), and `edit` — which always changes content — always has a hunk. A failed/aborted/policy-rejected mutation applied nothing, so it carries no `meta` and falls through to the generic error rendering (its message must show).
+
+### 3. The bridge renders a `diff` result card
+
+`ToolResultView` gains a `DiffResultView { card:'diff'; title?; diffs: FileDiff[] }`; the bridge's result-side `switch (view.card)` gets a `diff` arm emitting the `{type:'diff'}` `ToolCallContent` blocks (mirroring the call-side arm). An ACP `tool_call_update.content` REPLACES the call's content in an editor, so the result diff **supersedes** the call-time snippet (and keeps the model-facing result text from clobbering it) — the two-update sequence (call snippet, then result diff) matches `claude-agent-acp` exactly.
+
+### The diff algorithm — a third-party runtime dependency over vendoring
+
+Computing hunks-with-context is a solved problem with sharp edge cases (grouping, context coalescing, the trailing-newline marker). Rather than hand-roll it, `dsh-tool-fs` takes a runtime dependency on the npm [`diff`](https://www.npmjs.com/package/diff) package (a `^9.0.0` range, exact-pinned by the lockfile; it ships its own types) and uses its `structuredPatch`. The repo's default is to vendor Cordis-framework source, but that policy is about the *framework*; a leaf tool package taking a small, well-known, self-typed utility dependency is the same shape as `dsh-acp` depending on `@agentclientprotocol/sdk`. Vendoring a diff algorithm would be re-implementing a battle-tested one for no benefit — the [pre-release "foundation over blast radius"](../../../../AGENTS.md) reasoning does not argue for re-deriving standard algorithms. The dependency's output is normalized in one small module (`packages/fs/tool-fs/src/diff.ts`).
+
+## Non-goals
+
+- **Live incremental diff streaming.** The hunk is computed once, after the mutation completes; there is no per-keystroke diff.
+- **Diffing a binary/non-UTF-8 overwrite.** `before` is `null` for such a file (it has no text diff basis); the write still succeeds and the result renders a whole-file diff (`oldText: null`) rather than a contextual hunk.
+- **Rename/move diffs.** Only content diffs of a single resolved path.
+- **Bounding the overwrite diff basis.** An overwrite reads the whole prior file into memory to compute the contextual hunk (on top of the new content already held), so a very large text overwrite allocates both texts for a UI-only diff. A future refinement can bound the pre-read and fall back to a whole-file / no contextual diff above a size threshold; tracked as `TODO(overwrite-diff-bound)` at the read site.
+
+## Related
+
+- Completes the one remaining representation difference named as a non-goal in [Tagged render-intent union](2026-07-02-tool-render-intent-union.md) — that RFC's Non-goals section is updated to record that applied-hunk diffs shipped here.
+- Builds on the [filesystem capability seam](2026-06-17-filesystem-capability-seam.md) (the before/after are storage facts the backend returns) and [event-sourced sessions](2026-06-11-event-sourced-sessions.md) (the `meta` payload persists on the `tool/result` event, so replay reproduces the card).
+- The `meta` channel is deliberately generic: a future tool (a structured search, a data-table result) can attach its own durable result presentation without another core change.
--- a/docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md
+++ b/docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md
@@ -0,0 +1,70 @@
+# RFC: Tagged render-intent union for tool-call presentation
+
+Status: implemented
+
+## Problem
+
+A tool declares how its calls render in a UI (an editor's tool-call card) through two callbacks, `presentCall`/`presentResult` on `ToolDefinition`, returning `ToolCallPresentation` / `ToolResultPresentation` with an optional `ToolTerminal` sub-shape. These grew incrementally into a **bag of optional fields**: `title`, `kind`, `rawInput`, `content`, `locations`, `terminal` on the call; `title`, `content`, `terminal` on the result; `cwd`/`output`/`exitCode`/`signal` on `ToolTerminal`. The split of responsibility is muddy:
+
+- The call-side and result-side `terminal` fields overlap, and the bridge reconciles a `content` block AND a `terminal` block AND `rawInput` per call, stitching them together with ad-hoc conditionals.
+- Which combinations are *valid* is unwritten: a `terminal` call that also sets `content` means "description above the card"; a generic call that sets `terminal` is meaningless but representable. The type permits nonsense.
+- There is no way to express the one file-tool affordance an editor most wants — a **diff card** (`{path, oldText, newText}`, which Zed renders as an inline diff / new-file preview). `ToolCallPresentation.content` is the *LLM* `ContentBlock[]` vocabulary (text/image), so a tool literally cannot ask for a diff.
+
+The existing `FIXME(tool-presentation)` in `packages/core/tools/src/index.ts` named the fix: "redesign the type so a tool declares its render INTENT once (e.g. a tagged union over card kinds) rather than a bag of optional fields the bridge stitches together." The rejected RFC [Collapse tool-owned UI presentation](../../rejected/simplification/2026-06-20-generic-tool-rendering.md) deferred it explicitly: rich rendering "should return later as a tagged render-intent union after there are at least two real tools and two real consumers to validate the vocabulary." That bar is now met — two producer families (`dsh-tool-bash`, `dsh-tool-fs`) and two consumers (the ACP bridge live path + the snapshot-golden replay path).
+
+## Decision
+
+Replace the optional-field bag with a **`card`-tagged discriminated union**. A tool declares one render intent per call/result; the bridge switches on the tag.
+
+```ts ignore-check
+type FileLocation = { path: string; line?: number }
+type FileDiff = { path: string; oldText: string | null; newText: string } // oldText null ⇒ new file
+
+// presentCall → ToolCallView
+type ToolCallView = GenericCallView | TerminalCallView | DiffCallView
+interface GenericCallView { card: 'generic'; title: string; kind?: ToolCallKind; rawInput?: unknown; content?: ContentBlock[]; locations?: FileLocation[] }
+interface TerminalCallView { card: 'terminal'; title: string; description?: string; cwd?: string }
+interface DiffCallView { card: 'diff'; title: string; diffs: FileDiff[]; locations?: FileLocation[] }
+
+// presentResult → ToolResultView
+type ToolResultView = GenericResultView | TerminalResultView
+interface GenericResultView { card: 'generic'; title?: string; content?: ContentBlock[] }
+interface TerminalResultView { card: 'terminal'; title?: string; output?: string; exitCode?: number; signal?: string }
+```
+
+`card` is **required** on every variant — a real discriminant, not an optional default. The bridge does `switch (view.card) { case 'generic': … case 'terminal': … case 'diff': … default: assertNever(view) }`. The union is **closed** (per the [switch-exhaustiveness convention](../../../../AGENTS.md)): a fourth render intent (a table, a chart) needs new bridge code to render it anyway, so a plugin-added variant that the bridge silently drops would be worse than a compile error. Adding a variant breaks compilation at the bridge switch — exactly the signal we want.
+
+### Why a tagged union beats the field-bag
+
+- **Invalid states become unrepresentable.** A generic card cannot carry terminal output; a terminal card cannot carry a diff. The old bag permitted all of these.
+- **The bridge switches instead of stitching.** One arm per card kind, each producing exactly the wire shape that card needs, rather than reconciling five optional fields whose interactions are undocumented.
+- **`diff` is a first-class intent.** `dsh-tool-fs` write/edit declare `card:'diff'`; the bridge emits an ACP `{type:'diff', path, oldText, newText}` `ToolCallContent` (already in the SDK's `ToolCallContent` union, previously unused by the bridge). This is the affordance the redesign unlocks.
+
+### Producer mapping
+
+- `dsh-tool-fs` read → `generic` (`kind:'read'`, a follow-along `location`); write → `diff` (`oldText:null`); edit → `diff` (`oldText:old_string || null`, `newText:new_string ?? ''`). This mirrors `claude-agent-acp`'s `toolInfoFromToolUse` Read/Write/Edit arms field-for-field.
+- `dsh-tool-bash` foreground → `terminal` call + `terminal` result; `run_in_background` and `bash_output`/`bash_kill` → `generic`.
+- `dsh-tool-todo` → `generic`.
+
+### Terminal fallback ownership
+
+`TerminalResultView` carries only `output`/`exitCode`/`signal`. A UI without the terminal capability needs a fenced ` ```console ` text fallback; that derivation moves to the **bridge** (it wraps `output` in a fenced block on the no-capability path), rather than the tool double-encoding it. This keeps the bash tool's result a single structured shape and preserves the existing capability-gated behavior byte-for-byte.
+
+### Purity preserved
+
+`presentCall`/`presentResult` remain pure functions of `args` (+ the result for `presentResult`) — they run on live streaming AND session-log replay, so they must be replay-deterministic. Every view is derived from args alone: write's diff is new-file style (`oldText:null`) because the tool has no old content at call time; edit's diff is `old_string`→`new_string`.
+
+## Relative-path display titles
+
+`claude-agent-acp` relativizes a file card's title path against the session cwd (`toDisplayPath`) — `Read src/foo.ts`, not `/abs/proj/src/foo.ts` — while keeping `locations[]`/`diff.path` **raw** (the editor opens the real path). Our `presentCall` is pure/args-only and cannot see the session cwd, so this relativization happens at the **bridge**, which already threads the session cwd into tool-call rendering (the same cwd it uses to resolve a terminal card's header). The bridge relativizes the title only, by an exact structured replace of the known `locations[0].path`/`diffs[0].path` substring — generic over the file-card kinds, never special-casing tool names.
+
+## Non-goals
+
+- **Live incremental `terminal_output_delta` streaming** and **command classification** — the terminal-rendering RFC's own deferred follow-ups, untouched here.
+
+## Related
+
+- Supersedes the deferral in [Collapse tool-owned UI presentation](../../rejected/simplification/2026-06-20-generic-tool-rendering.md) (rejected — "wait for two real tools and two real consumers, then a tagged render-intent union"). That bar is now met; this is that union.
+- Extended by [Result-time applied-hunk diffs](2026-07-02-result-time-applied-hunk-diffs.md), which adds a persisted `meta` channel so write/edit emit a result-time `DiffResultView` — the applied change (a contextual hunk with context lines / one per `replace_all` site, or a whole-file diff for a create) — on top of this union's call-time diff card.
+- Folds `ToolTerminal` into the `terminal` views described by [ACP terminal and tool-call rendering](../feature/2026-06-18-acp-terminal-and-tool-rendering.md) (the `_meta` terminal-card convention and capability gate are unchanged; only the harness-side presentation type changes).
+- The ACP SDK's `Diff` / `ToolCallContent` types back the new `diff` card.
--- a/docs/rfc/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/docs/rfc/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -23,7 +23,7 @@ The rule that settled the remaining cases: ***the type you write, hold, or recei
 - A data structure is **core** if it flows through the agent-loop spine — the loop holds, derives, streams, or logs it on every turn regardless of which plugins load (`Message`, `StreamChunk`, `SessionEvent`, the `Agent` handle) — **or** it is the single headline type a plugin author writes against a pipeline (`ToolDefinition`).
 - `ToolDefinition` is core (it is what every tool author writes) **even though the loop never holds one** — authoring-importance overrides the strict flows-through-spine rule for this one headline type. But its typing machinery — the `SchemaSpec`/`InferArgs` DSL — is a sub-page detail (you write a `ToolDefinition`; the type-level machinery that types it you do not). That is the spine-vs-seam line made sharp.
 - `ToolSchema` is core (it is a field of `GenerateOptions`, the model request that flows through every step) even though it is conceptually part of the tool pipeline — *flows through the spine* wins over *conceptual home* when they conflict.
- The tool-presentation vocabulary (`ToolCallPresentation`, …, carrying a `FIXME(tool-presentation)` redesign marker), the `SessionPersistence` durability seam, and bash vocabulary are sub-pages.
+- The tool-presentation vocabulary (`ToolCallView`/`ToolResultView`, …), the `SessionPersistence` durability seam, and bash vocabulary are sub-pages.

 `core.md` is a **self-contained spine doc**: it states the exact type definition of each spine structure with minimal prose and links to sub-pages for the per-seam detail. The sub-pages are `llm-streaming.md`, `session.md`, `persistence.md` (split from session along the in-memory-model vs. durability-seam line), `tools.md`, and `bash.md`.

--- a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
+++ b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.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
+2026-07-02-bilingual-docs-and-pairing-gate.md: 517a6371eca5d747313c7efdb2756a50257701e4
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: f8f68bf5d4d7e6795318d9dd435a525f20a4f407
--- a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
+++ b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
@@ -0,0 +1,36 @@
+# Bilingual documentation via paired sibling files and a pairing gate
+
+English | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)
+
+## Context
+
+This repo's README and docs tree are read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.
+
+## Decision
+
+- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../i18n/terminology.md).
+- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.
+- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: required pairs exist, every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical), and excluded (generated or bilingual-by-construction) files stay unpaired. The `required` list in [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) is a ratchet: each merged translation batch adds its files, so coverage only grows.
+- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../../.agents/skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../../.agents/skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth.
+
+## Alternatives considered
+
+- **English as the canonical source with a fingerprint inside the translation** — the design first proposed for this RFC: `.zh.md` files carried an HTML comment recording the English source's blob hash, and translation flowed EN → ZH only. Revised in review: the team wants Chinese-first authoring (write and review a Chinese RFC, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.
+- **Locale directories (`docs/en/` + `docs/zh/`, the Kubernetes/ECharts model)** — rejected: this repo has no docs-site framework to map locales to routes, moving every English file would churn every existing cross-reference, and `verify-md-links`/`verify-doc-refs` would need path-mapping logic instead of working unchanged.
+- **A separate translation repo (the PingCAP `docs`/`docs-cn` model)** — rejected: right for a docs product with independent release trains, overkill for a monorepo's own documentation; it also puts the translation outside the reach of this repo's gates.
+- **Interleaved bilingual files (single file, both languages)** — rejected: doubles every diff, breaks the one-line-per-paragraph convention's diff ergonomics, and makes partial inconsistency invisible.
+- **Commit-hash records (the MDN `l10n.sourceCommit` model)** — rejected in favor of blob hashes: a same-PR edit has no commit hash yet, so the MDN model cannot express "consistent as of the state this PR introduces", and verifying it requires git history instead of file content.
+- **Comparing git timestamps of the pair (no record)** — rejected: formatting-only edits would false-positive, and a counterpart committed after an unrelated edit would false-negative; content identity is the only signal that means what the gate claims.
+
+## Industry precedent
+
+Paired sibling files with locale suffixes are the dominant Chinese big-tech convention (ant-design `index.zh-CN.md`/`index.en-US.md`; arco-design `README.zh-CN.md` with a top-of-file switcher; Apache ShardingSphere's 387 `.cn.md`/`.en.md` pairs) — but none of those repos *enforce* pairing or consistency in CI; the convention holds by review alone. Consistency automation exists outside China: MDN's `l10n.sourceCommit` front-matter fingerprint, Vue's Ryu-Cho action (upstream-commit watcher that opens issues/PRs for stale translations), Kubernetes' localization drift scripts, and Microsoft's Azure co-op-translator (source-hash-driven LLM re-translation in CI). This design combines the two: the Chinese-ecosystem file layout with a hash-pair gate, plus a committed agent skill in place of a bot service.
+
+## Consequences
+
+- Editing either side of a paired document obligates the same PR to update the counterpart and re-record the pair — the gate makes the doc-sync rule bilingual, and CI (not reviewer memory) carries the invariant.
+- Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, "who confirmed these consistent, and when" is answerable from git blame on the yaml.
+- When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.
+- Generated docs (`cordis-catalog/`, `tool-catalog/`, `module-graph.md`) are excluded for now; the planned follow-up is to teach their generators to emit Chinese alongside English, at which point they leave the exclusion list.
+- Rollout is incremental by design: documents outside `required` are visible backlog (`--list`), not red CI, so pairs land in reviewable batches without a big-bang PR.
+- The recorded hashes double as the update tool (`git cat-file -p <hash>` recovers either side's last-confirmed text for a minimal diff-based update), so re-translation of whole files is never forced by the mechanism.
--- a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
+++ b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
@@ -0,0 +1,36 @@
+# 通过配对兄弟文件与配对门禁实现双语文档
+
+[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文
+
+## 背景
+
+本仓库的 README 与 docs 目录树会被公司内外的人和 agent（智能体）以中英两种语言阅读。没有机制、纯靠手工维护第二语言，正是译文腐烂的方式：一侧继续演进，另一侧默默地说谎，而没有门禁会注意到。对这类不变式，本仓库一贯的答案是把它编码成机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。
+
+## 决策
+
+- **配对兄弟文件，两种语言同权。**一对文档是三个兄弟文件：英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典——一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束这对文件的是两侧必须说同样的话，且配对整体合入（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../i18n/terminology.md)。
+- **旁挂记录两侧 blob hash，使一致性可检查。**`foo.i18n.yaml` 保存两侧文件在上一次确认一致状态下各自的完整 git blob hash。此后改了任一侧而没重新确认配对，都能被机械检测出来——纯内容比较、无需查询历史——而且同一个 PR 里改动的文件也能算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write`）产生一份可评审的 yaml diff：确认一致在 PR 里是一个显式、可见的动作。
+- **`verify-translation-pairing` 加入 `doc-sync`。**门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行：required 的配对存在；任何已存在的配对完整（三个文件齐全）且一致（两个 hash 都匹配、切换行双向互链、结构签名一致）；被排除的文件（生成物或本身即双语的）保持不配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 中的 `required` 清单是一个棘轮：每个合入的翻译批次把自己的文件加进去，覆盖面只增不减。
+- **翻译是 agent 的工作，由人评审。**进仓的工作流是 [.agents/skills/dsh-translate-docs](../../../../.agents/skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../../.agents/skills/dsh-code-review/SKILL.md) 同一模式：skill 承载工作流，并把真源让给文档。
+
+## 曾考虑的替代方案
+
+- **英文为正典源、指纹放在译文内**——本 RFC 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 RFC，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的旁挂记录取代了文件内的单向指纹；blob hash 的机制原样保留。
+- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**——否决：本仓库没有把 locale 映射到路由的文档站框架，挪动每个英文文件会搅动所有既有交叉引用，且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑而不是原样工作。
+- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**——否决：适合有独立发布节奏的文档产品，对 monorepo 自己的文档而言过重；还会把译文置于本仓库门禁够不到的地方。
+- **中英混排单文件（一个文件、两种语言）**——否决：每个 diff 都翻倍，破坏一段一行约定的 diff 工效，且局部不一致不可见。
+- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**——否决，改用 blob hash：同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。
+- **比较配对两侧的 git 时间戳（无记录）**——否决：纯格式化的改动会误报，一次无关改动之后提交的另一侧会漏报；只有内容同一性这个信号与门禁的承诺名实相符。
+
+## 业界先例
+
+带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`）——但这些仓库都没有在 CI 里**强制**配对或一致性；约定纯靠评审维系。一致性自动化存在于中国之外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit、为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计把两者结合：中文生态的文件布局，加 hash 对门禁，再加一个进仓 agent skill（技能）替代 bot 服务。
+
+## 后果
+
+- 修改已配对文档的任一侧，同一个 PR 就有义务更新另一侧并重新记录配对——门禁把 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。
+- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对一致」可以从 yaml 的 git blame 直接回答。
+- 两侧说法冲突时，没有机械规则裁决谁赢——由 PR 评审裁决。这是同权的代价，是有意接受的：另一个选项（正典语言）禁止中文先行撰写。
+- 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让它们的生成器在输出英文的同时输出中文，届时移出排除清单。
+- 推进天然是渐进的：`required` 之外的文档是可见的 backlog（`--list`），不是红的 CI，因此配对按可评审的批次落地，无需一个巨型 PR。
+- 记录的 hash 兼作更新工具（`git cat-file -p <hash>` 能还原任一侧上次确认的文本，用于基于 diff 的最小更新），所以这套机制从不强迫整篇重译。