docs: enforce localized release doc parity

refs #1151

6 files changed, 144 insertions, 0 deletions

diff --git a/docs/next/website/src/content/docs/ja/cli-reference.mdx b/docs/next/website/src/content/docs/ja/cli-reference.mdx
index f3a8d015..ea15d44d 100644
--- a/docs/next/website/src/content/docs/ja/cli-reference.mdx
+++ b/docs/next/website/src/content/docs/ja/cli-reference.mdx
@@ -19,6 +19,7 @@ herdr --no-session            # シングルプロセスの逃げ道
 herdr --default-config        # デフォルト設定を表示
 herdr update                  # 設定済みチャンネルからダウンロードしてインストール
 herdr update --handoff        # 対応する実行中サーバーでライブハンドオフにオプトイン
+herdr completion zsh          # zsh 補完スクリプトを生成
 herdr channel show            # stable または preview を表示
 herdr channel set preview     # プレビュービルドにオプトイン
 herdr channel set stable      # Linux/macOS の直接インストールを安定版に戻す
@@ -33,6 +34,48 @@ herdr status server
 herdr status client
 ```
 
+API スキーマコマンド:
+
+```bash
+herdr api schema
+herdr api schema --json
+herdr api schema --output herdr-api.schema.json
+```
+
+`herdr api schema` は、インストール済みバイナリに同梱されたソケットプロトコルスキーマの短い概要を表示します。完全な JSON Schema ドキュメントが欲しいときは `--json` を使い、ファイルに書き出すには `--output PATH` を使ってください。
+
+## シェル補完
+
+```bash
+herdr completion zsh
+herdr completions zsh
+herdr completion bash
+herdr completion fish
+herdr completion powershell
+herdr completion elvish
+```
+
+`completion` はスクリプトを標準出力に表示します。`completions` はエイリアスです。一時的な zsh セッションでは、スクリプトを直接読み込めます:
+
+```bash
+source <(herdr completion zsh)
+```
+
+永続的な zsh 設定では、生成された `_herdr` 関数を `compinit` が実行される前の `fpath` 上に置いてください:
+
+```bash
+mkdir -p ~/.zfunc
+herdr completion zsh > ~/.zfunc/_herdr
+```
+
+その後、`.zshrc` に次の内容があることを確認してください:
+
+```zsh
+fpath=(~/.zfunc $fpath)
+autoload -Uz compinit
+compinit
+```
+
 ## サーバー
 
 ```bash
diff --git a/docs/next/website/src/content/docs/ja/socket-api.mdx b/docs/next/website/src/content/docs/ja/socket-api.mdx
index dca7136d..a5ebc5f5 100644
--- a/docs/next/website/src/content/docs/ja/socket-api.mdx
+++ b/docs/next/website/src/content/docs/ja/socket-api.mdx
@@ -17,6 +17,18 @@ Herdr は、実行中のセッションを調査・制御する必要がある�
 
 これらの層は同じ制御面を共有します。
 
+## スキーマ
+
+インストール済み CLI は、その Herdr バイナリに同梱されたソケットプロトコルスキーマを表示できます:
+
+```bash
+herdr api schema
+herdr api schema --json
+herdr api schema --output herdr-api.schema.json
+```
+
+通常の `herdr api schema` は短い概要を表示します。`--json` はツール向けの完全な JSON Schema を表示し、`--output PATH` はそのドキュメントをファイルに書き込みます。スキーマには、生のリクエスト、成功レスポンス、エラーレスポンス、発行イベント、購読イベントが含まれます。
+
 ## 制御できるもの
 
 ソケット API では次のことができます:
diff --git a/docs/next/website/src/content/docs/ja/windows-beta.mdx b/docs/next/website/src/content/docs/ja/windows-beta.mdx
index 9d282a70..f6b45500 100644
--- a/docs/next/website/src/content/docs/ja/windows-beta.mdx
+++ b/docs/next/website/src/content/docs/ja/windows-beta.mdx
@@ -57,6 +57,23 @@ Windows Terminal は特定のエージェント向けに画像貼り付け経路
 
 Kitty graphics は実験的なままで、まだ Windows でのサポートを謳っていません。Windows Terminal での画像レンダリングを特にテストしているのでない限り、`experimental.kitty_graphics = false` のままにしてください。
 
+## 既知の注意点
+
+### カーソル描画
+
+Windows のターミナルは ConPTY 経由で Herdr を実行するため、フルスクリーン再描画中にネイティブの端末カーソルがちらついたり、ジャンプしたり、古い位置を一瞬表示したりすることがあります。Herdr のデフォルト `host_cursor = "auto"` は、Windows では Herdr のカーソルを端末セルの内容として描画し、Linux と macOS ではネイティブの端末カーソルを使い続けます。Windows でのトレードオフは、外側ターミナルのネイティブな点滅、形状、カーソル色の代わりに、Herdr 内で安定した非点滅カーソルを表示することです。
+
+Windows で外側ターミナルのカーソルに戻すには、次を設定してください:
+
+```toml
+[ui]
+host_cursor = "native"
+```
+
+### キーボードとマウス
+
+Windows のターミナルは、修飾キー付きのキーをすべて同じ形で報告するわけではありません。Herdr は Windows Terminal と Windows 上の Alacritty ではマウス報告と `ctrl+j` を保持しますが、`shift+enter` は外側ターミナルが修飾付き Enter として区別して報告する場合にだけ動作します。Windows またはターミナルがそれを通常の Enter として報告する場合、Herdr は通常の Enter を転送します。
+
 ## コピーと貼り付け
 
 Herdr のペインテキストコピーは Windows ベータで動作します。ペイン内でテキストをドラッグ選択すると Herdr 経由でコピーされます。
diff --git a/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx b/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx
index 91a7b205..c32b14bc 100644
--- a/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx
+++ b/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx
@@ -19,6 +19,7 @@ herdr --no-session            # 单进程逃生舱
 herdr --default-config        # 打印默认配置
 herdr update                  # 从配置的通道下载并安装
 herdr update --handoff        # 对受支持的运行中服务器启用实时交接
+herdr completion zsh          # 生成 zsh 补全脚本
 herdr channel show            # 打印 stable 或 preview
 herdr channel set preview     # 启用预览构建
 herdr channel set stable      # 把 Linux/macOS 直接安装切回稳定版
@@ -33,6 +34,48 @@ herdr status server
 herdr status client
 ```
 
+API schema 命令:
+
+```bash
+herdr api schema
+herdr api schema --json
+herdr api schema --output herdr-api.schema.json
+```
+
+`herdr api schema` 会打印安装的二进制中包含的 socket 协议 schema 简短摘要。需要完整 JSON Schema 文档时使用 `--json`;要写入文件则使用 `--output PATH`。
+
+## Shell 补全
+
+```bash
+herdr completion zsh
+herdr completions zsh
+herdr completion bash
+herdr completion fish
+herdr completion powershell
+herdr completion elvish
+```
+
+`completion` 会把脚本打印到 stdout。`completions` 是别名。临时 zsh 会话可以直接加载脚本:
+
+```bash
+source <(herdr completion zsh)
+```
+
+持久 zsh 设置中,把生成的 `_herdr` 函数写到 `compinit` 运行前已经在 `fpath` 上的位置:
+
+```bash
+mkdir -p ~/.zfunc
+herdr completion zsh > ~/.zfunc/_herdr
+```
+
+然后确认 `.zshrc` 包含:
+
+```zsh
+fpath=(~/.zfunc $fpath)
+autoload -Uz compinit
+compinit
+```
+
 ## 服务器
 
 ```bash
diff --git a/docs/next/website/src/content/docs/zh-cn/socket-api.mdx b/docs/next/website/src/content/docs/zh-cn/socket-api.mdx
index 3a5320b8..7454ecc7 100644
--- a/docs/next/website/src/content/docs/zh-cn/socket-api.mdx
+++ b/docs/next/website/src/content/docs/zh-cn/socket-api.mdx
@@ -17,6 +17,18 @@ Herdr 为需要检查或控制运行中会话的脚本和智能体提供了一�
 
 这些层共享同一套控制面。
 
+## Schema
+
+安装的 CLI 可以打印该 Herdr 二进制中包含的 socket 协议 schema:
+
+```bash
+herdr api schema
+herdr api schema --json
+herdr api schema --output herdr-api.schema.json
+```
+
+普通的 `herdr api schema` 打印简短摘要。`--json` 打印供工具使用的完整 JSON Schema,`--output PATH` 将该文档写入文件。schema 覆盖原始请求、成功响应、错误响应、发出的事件和订阅事件。
+
 ## 你能控制什么
 
 socket API 可以:
diff --git a/docs/next/website/src/content/docs/zh-cn/windows-beta.mdx b/docs/next/website/src/content/docs/zh-cn/windows-beta.mdx
index e092451a..971835ca 100644
--- a/docs/next/website/src/content/docs/zh-cn/windows-beta.mdx
+++ b/docs/next/website/src/content/docs/zh-cn/windows-beta.mdx
@@ -57,6 +57,23 @@ Windows Terminal 可能为特定智能体支持图像粘贴路径,但 Herdr 自�
 
 Kitty graphics 仍是实验性功能,尚未宣称支持 Windows。除非你专门在 Windows Terminal 中测试图像渲染,否则保持 `experimental.kitty_graphics = false`。
 
+## 已知注意事项
+
+### 光标渲染
+
+Windows 终端通过 ConPTY 运行 Herdr,在活跃的全屏重绘期间,原生终端光标可能闪烁、跳动,或短暂显示旧位置。Herdr 默认的 `host_cursor = "auto"` 会在 Windows 上把 Herdr 光标绘制为终端单元格内容,而 Linux 和 macOS 继续使用原生终端光标。Windows 上的取舍是:在 Herdr 内得到稳定的不闪烁光标,但不使用外层终端的原生闪烁、形状和光标颜色。
+
+要在 Windows 上改回外层终端光标,请设置:
+
+```toml
+[ui]
+host_cursor = "native"
+```
+
+### 键盘和鼠标
+
+Windows 终端并不都以相同形式报告带修饰键的按键。Herdr 在 Windows Terminal 和 Windows 上的 Alacritty 中保留鼠标报告和 `ctrl+j`,但 `shift+enter` 只有在外层终端把它报告为独立的修饰 Enter 键时才有效。如果 Windows 或终端把它报告为普通 Enter,Herdr 会转发普通 Enter。
+
 ## 复制与粘贴
 
 Herdr 的窗格文本复制在 Windows 测试版上可用。在窗格内拖选文本即可通过 Herdr 复制。