diff --git a/website/src/content.config.ts b/website/src/content.config.ts
index bb0f2d8a..e84e3781 100644
--- a/website/src/content.config.ts
+++ b/website/src/content.config.ts
@@ -3,9 +3,17 @@ import { glob } from 'astro/loaders';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';
+const docsLocales = ['ja', 'zh-cn'];
+
function docsPath({ entry }: { entry: string }) {
const slug = entry.replace(/\.(md|mdx|markdown|mdown|mkdn|mkd|mdwn)$/i, '');
const normalized = slug.replace(/\/index$/, '');
+ for (const locale of docsLocales) {
+ if (normalized === locale) return `${locale}/docs`;
+ if (normalized.startsWith(`${locale}/`)) {
+ return `${locale}/docs/${normalized.slice(locale.length + 1)}`;
+ }
+ }
return normalized === 'index' ? 'docs' : `docs/${normalized}`;
}
diff --git a/website/src/content/docs/ja/agent-skill.mdx b/website/src/content/docs/ja/agent-skill.mdx
new file mode 100644
index 00000000..1fc6405d
--- /dev/null
+++ b/website/src/content/docs/ja/agent-skill.mdx
@@ -0,0 +1,65 @@
+---
+title: エージェントスキルファイル
+description: Claude Code などのコーディングエージェントに Herdr の使い方をインストールします。
+---
+
+Herdr は再利用可能なエージェントスキルファイルを [`SKILL.md`](https://github.com/ogulcancelik/herdr/blob/master/SKILL.md) として提供しています。
+
+このファイルを、再利用可能なスキルやカスタム指示に対応した任意のコーディングエージェントにインストールしてください。このスキルは、Herdr のペイン内から Herdr を制御する方法をエージェントに教えます。
+
+Herdr は別の用途向けに [`herdr.dev/agent-guide.md`](https://herdr.dev/agent-guide.md) というガイドも提供しています。こちらは、人間が Herdr を学習・セットアップ・トラブルシューティングするのをエージェントが手伝うためのものです。スキルは Herdr を操作するエージェントのため、ガイドは人間に教えるエージェントのためのものです。
+
+## スキルがすること
+
+このスキルは、`HERDR_ENV=1` が設定されているときに `herdr` CLI を使うようエージェントに指示します。これは、エージェントが Herdr 管理下のペイン内で動作しており、ローカルの Herdr ソケットと安全に通信できることを意味します。
+
+スキルをインストールすると、エージェントは次のことができます:
+
+- ワークスペース、タブ、ペイン、隣のエージェントを調べる
+- フォーカスを奪わずにペインを分割してコマンドを実行する
+- ペインの出力と最近のログを読む
+- サーバー、テスト、別のエージェントの完了を待つ
+- 隣のペインでヘルパーエージェントを起動する
+
+このスキルは独立したアプリやサービスではありません。エージェント向けの markdown 指示ファイルです。
+
+## インストールする
+
+`npx skills` でスキルをインストールします:
+
+```bash
+npx skills add ogulcancelik/herdr --skill herdr -g
+```
+
+`-g` フラグは、対応エージェントにグローバルインストールします。現在のプロジェクトにインストールする場合は `-g` を省略してください。
+
+手動でのフォールバックおよび信頼できるソースとしては、リポジトリのコピーを使ってください:
+
+```text
+https://github.com/ogulcancelik/herdr/blob/master/SKILL.md
+```
+
+スキルシステムを持つエージェントには、このファイルを `herdr` という名前のスキルとしてインストールしてください。スキルシステムを持たないエージェントには、ファイルの内容をプロジェクト指示またはユーザー指示に貼り付けてください。
+
+インストール後、Herdr の中でエージェントを起動します:
+
+```bash
+herdr
+claude
+```
+
+他のコーディングエージェントを Herdr のペインで使っても構いません。重要なのは、エージェントのプロセスが Herdr 内で動作していて `HERDR_ENV=1` が利用できることです。
+
+## 安全ルール
+
+このスキルはひとつのガードレールから始まります: `HERDR_ENV=1` が設定されていない場合、エージェントは停止して、Herdr 管理下のペイン内で動作していないと伝えるべきです。
+
+これにより、Herdr の外にいるエージェントが自分のものではないセッションを制御しようとするのを防ぎます。
+
+## エージェント向けリファレンス
+
+コマンドの完全なガイドはスキルファイル自体にあります。ペイン ID、`pane split`、`pane run`、`pane read`、`wait output`、`wait agent-status`、ワークスペースとタブのコマンド、協調動作のレシピを扱っています。
+
+ソースファイルはこちら:
+
+[GitHub で `SKILL.md` を開く →](https://github.com/ogulcancelik/herdr/blob/master/SKILL.md)
diff --git a/website/src/content/docs/ja/agents.mdx b/website/src/content/docs/ja/agents.mdx
new file mode 100644
index 00000000..60a6451c
--- /dev/null
+++ b/website/src/content/docs/ja/agents.mdx
@@ -0,0 +1,163 @@
+---
+title: エージェント
+description: Herdr が何を検出できるか、エージェント状態の仕組み、インテグレーションによる精度向上。
+---
+
+Herdr は複数のコーディングエージェントを同時に動かすために作られています。各エージェントは、シェル、ログ、プロンプト、実行中プロセスをそのまま保った実際のターミナルペインの中にいます。Herdr はどのペインにエージェントがいるかを追跡し、その状態をタブとワークスペースに集約し、すべてのターミナルを手作業で見回る代わりに、注意が必要なペインへ直接ジャンプできるようにします。
+
+## 対応エージェント
+
+一般的なコーディングエージェントは、追加設定なしで自動検出されます。重要な違いは Herdr がエージェントを見えるかどうかではありません。どのシグナルが `idle`、`working`、`blocked` を決定する権限を持つかです。
+
+| エージェント | 状態の権威 | インテグレーションの役割 |
+| --- | --- | --- |
+| Pi | インストール時はライフサイクルフック。それ以外はスクリーンマニフェスト | 状態とセッション |
+| OMP | インストール時はライフサイクルフック | 状態 |
+| GitHub Copilot CLI | スクリーンマニフェスト | セッション |
+| Devin CLI | スクリーンマニフェスト | セッション |
+| Kimi Code CLI | インストール時はライフサイクルフック。それ以外はスクリーンマニフェスト | 状態とセッション |
+| Hermes Agent | インストール時はライフサイクルフック。それ以外はスクリーンマニフェスト | 状態とセッション |
+| Qoder CLI | スクリーンマニフェスト | セッション |
+| Droid | スクリーンマニフェスト | セッション |
+| OpenCode | インストール時はライフサイクルプラグイン。それ以外はスクリーンマニフェスト | 状態とセッション |
+| Kilo Code CLI | インストール時はライフサイクルプラグイン。それ以外はスクリーンマニフェスト | 状態とセッション |
+| Claude Code | スクリーンマニフェスト | セッション |
+| Codex | スクリーンマニフェスト | セッション |
+| Cursor Agent CLI | スクリーンマニフェスト | セッション |
+| Amp | スクリーンマニフェスト | なし |
+| Grok CLI | スクリーンマニフェスト | なし |
+| Antigravity CLI | スクリーンマニフェスト | なし |
+| Kiro CLI | スクリーンマニフェスト | なし |
+
+検出されるもののテストが薄いもの: Gemini CLI と Cline。未対応のエージェントも通常のターミナルプロセスとして問題なく動きます。ただし、インテグレーションを追加するかソケット API で状態を報告しない限り、詳細な状態は得られない可能性があります。
+
+## 状態の権威
+
+Herdr はまず各ペインのフォアグラウンドプロセスを検出します。その後、各ペインはひとつの状態権威を持ちます。
+
+完全なライフサイクルフックを持つエージェントでは、インテグレーションがインストールされ、実行中のペインについて能動的に報告している間は、インテグレーションが権威です。Herdr はそのフック報告を `idle`、`working`、`blocked` とセッション識別に使います。同じライフサイクル権威に対してスクリーンマニフェストのフォールバックを並走させることはしません。これにより、真実の情報源が 2 つ競合する状況を避けます。
+
+完全なライフサイクルフックを持たないエージェントでは、Herdr はフォアグラウンドプロセスを識別し、ライブの下部バッファのスクリーンスナップショットを読みます。そのスナップショットに対して TOML マニフェストを評価し、`idle`、`working`、`blocked` を分類します。それらを発するエージェントでは、マニフェストはターミナルタイトルと進捗 (OSC) シーケンスも検出の証拠としてマッチできます。その証拠がない場合は、スクリーンルールが単独で検出を担います。
+
+スクリーンスナップショットは、スクロールされたビューポートではなく、ペインバッファの直近の下部から取得されます。Herdr でスクロールバックしても、検出は下部のライブなエージェント UI を追い続けます。
+
+Claude Code、Codex、GitHub Copilot CLI、Droid、Qoder CLI、Cursor Agent CLI のインテグレーションは、意図的にライフサイクル権威にしていません。これらは復元のためのネイティブセッション識別を提供しますが、フックがライフサイクル全体をカバーしていません。許可承認の結果、Esc による中断、その他の遷移を見逃すことがあります。これらのエージェントでは、Herdr は引き続きスクリーンマニフェスト検出を使います。
+
+## VM とサンドボックスラッパー
+
+Linux では、VM、Bubblewrap、`fence` のようなラッパーがホストの `/proc` から実際のエージェントプロセスを隠すことがあります。コマンドに `HERDR_AGENT=
` を設定して (例: `HERDR_AGENT=claude fence -- claude`)、どの既存エージェントのスクリーンマニフェストを使うべきか Herdr に伝えてください。このヒントはそのフォアグラウンドプロセスにスコープされます。継承されるすべてのフォアグラウンドプロセスをそのエージェントとして扱いたいのでない限り、シェルからグローバルに export するのは避けてください。
+
+## blocked 状態
+
+スクリーンマニフェスト方式のエージェントでは、blocked の検出は意図的に厳格です。Herdr が `blocked` と判定するのは、ライブの下部バッファスナップショットが既知の承認・質問・許可 UI にマッチしたときだけです。既知のエージェントでどのマニフェストルールにもマッチしない場合、Herdr は `idle` にフォールバックし、explain の出力ではそのフォールバックに `default_known_agent_idle_fallback` というラベルを付けます。
+
+つまり、見慣れない新しいエージェントプロンプトは、Herdr がその画面の形を学習するまで、最初は `blocked` ではなく `idle` と表示されることがあります。こうしたやり取りによって Herdr が入力を送ったり破壊的な操作をしたりすることはありません。影響するのは表示上の状態と wait だけです。
+
+## 検出マニフェスト
+
+バンドルされたマニフェストは Herdr の内部にあります。Herdr は herdr.dev でリモートマニフェストの更新も確認し、有効なエージェント別ルール更新を Herdr の再起動なしで自動適用します。リモートマニフェストは Herdr の state ディレクトリに保存されます。バックグラウンドのリモートマニフェスト確認を無効にするには `[update] manifest_check = false` を設定します。
+
+ローカルオーバーライドは、プラットフォームの設定ディレクトリからリモートまたはバンドルのマニフェストを置き換えられます:
+
+```text
+~/.config/herdr/agent-detection/.toml
+```
+
+ローカルオーバーライドが常に優先されます。ローカルオーバーライドがない場合、Herdr はキャッシュされたリモートマニフェストと実行中バイナリにバンドルされたマニフェストのうち、新しくて互換性のある方を使います。デバッグビルドでは、同じ設定ヘルパーが `herdr-dev` のような開発用ディレクトリを使うことがあります。無効なオーバーライドファイルは警告付きで無視され、Herdr はそのエージェントについてキャッシュされたリモートまたはバンドルのマニフェストにフォールバックします。
+
+リモートマニフェストは、Herdr がすでに識別方法を知っているエージェントの検出ルールにパッチを当てるものです。完全に新しいエージェントの追加には、プロセス検出、ラベル、インテグレーション挙動のために Herdr バイナリのアップデートが引き続き必要です。
+
+実行中のサーバーは起動時にアクティブなマニフェストをメモリに読み込みます。リモートマニフェストの自動更新は、新しいルールが書き込まれた後にそのメモリ内キャッシュをリロードします。`herdr server update-agent-manifests` を実行すると、リモートマニフェストの更新を即座に取得して実行中のサーバーをリロードします。ローカルオーバーライドを手で編集した後は、Herdr を再起動するか `herdr server reload-agent-manifests` を実行して、実行中のサーバーにファイルを適用してください。
+
+ペインの状態表示がおかしいときは `herdr agent explain` を使ってください:
+
+```bash
+herdr agent explain
+herdr agent explain --file screen.txt --agent codex --json
+```
+
+ライブの explain は実行中のサーバーが評価するので、アクティブなマニフェストキャッシュを反映します。explain の出力には次が表示されます: エージェント、最終状態、完全なライフサイクル権威によってスクリーン検出がスキップされたかどうか、マニフェストのソースとバージョン、キャッシュされたリモートバージョン、ローカルオーバーライドによるシャドーイング、リモート更新の状況、マッチしたルール、可視の証拠フラグ、評価されたルールのマッチャーとリージョンの証拠、トランスクリプトビューアーでの更新スキップ理由、そしてどのルールにもマッチしなかったときの idle フォールバック理由です。
+
+Herdr は外側のターミナル環境として tmux の中で動かせます。エージェント検出は、Herdr のペイン内で起動された tmux セッションの中までは調べません。シェルフレームワークが Herdr 内で自動的に tmux に入る場合、Herdr はペインのプロセスとして背後のエージェントではなく `tmux` を見ることになります。
+
+## 状態のロールアップ
+
+サイドバーは状態を上位へ集約します。
+
+blocked なエージェントは、そのペイン、タブ、ワークスペースを blocked に見せます。working なエージェントはワークスペースをアクティブに見せます。done なエージェントは、あなたが確認するまで表示され続けます。
+
+これが Herdr の中心的なワークフローです: 複数のエージェントを起動し、並行して働かせ、サイドバーでどのプロジェクトが判断を必要としているか、どれがまだ実行中か、どれがレビュー待ちかを把握します。
+
+## ダイレクトインテグレーション
+
+使っている各エージェントのインテグレーションをインストールしてください。スクリーン検出だけに頼らず、フックやプラグインの報告を Herdr に提供します:
+
+```bash
+herdr integration install claude
+herdr integration status
+```
+
+対応エージェントごとに、インテグレーションの名前と挙動は異なります。エージェント別の詳細と完全なインストール一覧は[インテグレーション](/ja/docs/integrations/)を参照してください。
+
+## カスタムエージェントラベル
+
+表示用にエージェントターゲットの名前を変えられます:
+
+```bash
+herdr agent rename w1:p1 reviewer
+herdr agent rename reviewer --clear
+```
+
+ターゲットにはターミナル ID、一意なエージェント名、検出または報告されたエージェントラベル、レガシーなペイン ID が使えます。
+
+## カスタムステータスラベル
+
+インテグレーションは、意味的な状態を変えずに表示用ステータスラベルを報告できます。
+
+```bash
+herdr pane report-agent w1:p1 \
+ --source custom:indexer \
+ --agent docs-bot \
+ --state working \
+ --custom-status indexing
+```
+
+`state` は wait、通知、ロールアップを制御します。`custom-status` は表示テキストだけです。
+
+## CLI からエージェントを起動する
+
+ターミナルをエージェントターゲットとして扱いたいときは `herdr agent ...` コマンドを使います。エージェントターゲットは `agent list` に表示され、エージェント名で読み取りや入力送信ができ、エージェント状態で wait でき、直接アタッチできます。
+
+スクリプトから Herdr にエージェントを起動します:
+
+```bash
+herdr agent start reviewer --cwd ~/project --split right -- pi
+```
+
+特定のワークスペースやタブに配置することもできます:
+
+```bash
+herdr agent start docs --workspace w1 --tab w1:t1 -- claude
+```
+
+通常のターミナル、サーバー、テスト、シェル、低レベルなターミナル入力には `herdr pane ...` コマンドを使ってください。たとえば `cargo test` には `agent start` ではなく `pane split` と `pane run` を使います。そのターミナルを意図的にエージェントターゲットとして扱うのでない限り。
+
+## エージェントに直接アタッチする
+
+完全な Herdr UI ではなく、ひとつのエージェントターミナルに現在のターミナルをアタッチします:
+
+```bash
+herdr agent attach reviewer
+```
+
+`ctrl+b q` でデタッチします。リテラルの `ctrl+b` は `ctrl+b ctrl+b` で送ります。
+
+マウスホイールまたは通常の page up/page down でスクロールします。通常の入力をすると最下部に戻ります。
+
+別のダイレクトアタッチクライアントがすでに入力を所有している場合は `--takeover` を使います:
+
+```bash
+herdr agent attach reviewer --takeover
+```
+
+エージェントではないターミナルで同じダイレクトアタッチ挙動が欲しいときは `herdr terminal attach ` を使ってください。
diff --git a/website/src/content/docs/ja/cli-reference.mdx b/website/src/content/docs/ja/cli-reference.mdx
new file mode 100644
index 00000000..53559ea0
--- /dev/null
+++ b/website/src/content/docs/ja/cli-reference.mdx
@@ -0,0 +1,356 @@
+---
+title: CLI リファレンス
+description: セッション、ワークスペース、タブ、ペイン、通知、エージェント、wait、インテグレーション、ステータスのための Herdr コマンド。
+---
+
+Herdr の CLI は、インテグレーションやエージェントが使うのと同じローカルソケット API を通じて、実行中のサーバーと通信します。
+
+ほとんどのコマンドは JSON レスポンスを出力します。決定的な自動化が欲しいときはスクリプトから使ってください。
+
+## 起動とステータス
+
+```bash
+herdr # デフォルトセッションを起動またはアタッチ
+herdr --session work # 名前付きセッションを起動またはアタッチ
+herdr --remote workbox # SSH 越しにアタッチ (ローカルのキーバインドを使用)
+herdr --remote workbox --remote-keybindings server
+herdr --remote workbox --handoff
+herdr --no-session # シングルプロセスの逃げ道
+herdr --default-config # デフォルト設定を表示
+herdr update # 設定済みチャンネルからダウンロードしてインストール
+herdr update --handoff # 対応する実行中サーバーでライブハンドオフにオプトイン
+herdr channel show # stable または preview を表示
+herdr channel set preview # プレビュービルドにオプトイン
+herdr channel set stable # Linux/macOS の直接インストールを安定版に戻す
+herdr --version # バージョンを表示
+```
+
+ステータスコマンド:
+
+```bash
+herdr status
+herdr status server
+herdr status client
+```
+
+## サーバー
+
+```bash
+herdr server
+herdr server stop
+herdr server reload-config
+herdr server agent-manifests [--json]
+herdr server update-agent-manifests [--json]
+herdr server reload-agent-manifests
+```
+
+`herdr server` はヘッドレスサーバーを明示的に起動します。監視下やサービス的な構成で使ってください。`reload-config` はペインを再起動せずにリロード可能な設定を適用します。`agent-manifests` は、アクティブなエージェント検出マニフェストのソース、キャッシュされたリモートバージョン、直近のリモート更新結果を表示します。`update-agent-manifests` はリモートマニフェストの更新を即座に取得し、実行中のサーバーにリロードして、更新後のマニフェスト状態を表示します。生のステータスレスポンスが欲しいときは `--json` を渡してください。`reload-agent-manifests` は、ローカルオーバーライドの編集後にエージェント検出マニフェストを実行中のサーバーにリロードします。
+
+## 通知
+
+```bash
+herdr notification show [--body TEXT] [--position top-left|top-right|bottom-left|bottom-right] [--sound none|done|request]
+```
+
+`notification show` は設定済みの `[ui.toast]` 配信を使います。`--position` はアプリ内の Herdr トーストにのみ影響します。`--sound` のデフォルトは `none` で、`done` と `request` は通知が表示されたときにのみ、既存の完了音と要注意音を再生します。
+
+## セッション
+
+```bash
+herdr session list [--json]
+herdr session attach <name>
+herdr session stop <name> [--json]
+herdr session delete <name> [--json]
+```
+
+デフォルトセッションを明示的に停止する必要があるときは、セッション名として `default` を使ってください。
+
+## ワークスペース
+
+```bash
+herdr workspace list
+herdr workspace create [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [--no-focus]
+herdr workspace get <workspace_id>
+herdr workspace focus <workspace_id>
+herdr workspace rename <workspace_id> <label>
+herdr workspace close <workspace_id>
+```
+
+フォーカスを奪わずにワークスペースを作成します:
+
+```bash
+herdr workspace create --cwd ~/project --label api --no-focus
+```
+
+## Worktree
+
+```bash
+herdr worktree list [--workspace ID | --cwd PATH] [--json]
+herdr worktree create [--workspace ID | --cwd PATH] [--branch NAME] [--base REF] [--path PATH] [--label TEXT] [--focus] [--no-focus] [--json]
+herdr worktree open [--workspace ID | --cwd PATH] (--path PATH | --branch NAME) [--label TEXT] [--focus] [--no-focus] [--json]
+herdr worktree remove --workspace ID [--force] [--json]
+```
+
+worktree は、Git チェックアウトの出自情報を持つ通常の Herdr ワークスペースです。`worktree create` は Git worktree のチェックアウトを作成し、ワークスペースとして開き、親リポジトリのワークスペースとグループ化します。`--branch` が既存のローカルブランチを指す場合はそれをチェックアウトし、そうでなければ `--base` または `HEAD` からブランチを作成します。`--path` がない場合、チェックアウトは `<worktrees.directory>/<repo>/<branch-slug>` の下に作成されます。
+
+`workspace close` は Herdr の状態だけを閉じます。`worktree remove` が明示的なチェックアウト削除の経路です。`git worktree remove` を実行し、ブランチは決して削除せず、Git がダーティなチェックアウトを拒否する場合は `--force` が必要です。
+
+## タブ
+
+```bash
+herdr tab list [--workspace <workspace_id>]
+herdr tab create [--workspace <workspace_id>] [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [--no-focus]
+herdr tab get <tab_id>
+herdr tab focus <tab_id>
+herdr tab rename <tab_id> <label>
+herdr tab close <tab_id>
+```
+
+## ペイン
+
+```bash
+herdr pane list [--workspace <workspace_id>]
+herdr pane current [--pane ID|--current]
+herdr pane get <pane_id>
+herdr pane layout [--pane ID|--current]
+herdr pane process-info [--pane ID|--current]
+herdr pane neighbor --direction left|right|up|down [--pane ID|--current]
+herdr pane edges [--pane ID|--current]
+herdr pane focus --direction left|right|up|down [--pane ID|--current]
+herdr pane resize --direction left|right|up|down [--amount FLOAT] [--pane ID|--current]
+herdr pane zoom [<pane_id>|--pane ID|--current] [--toggle|--on|--off]
+herdr pane rename <pane_id> <label>|--clear
+herdr pane split [<pane_id>|--pane ID|--current] --direction right|down [--ratio FLOAT] [--cwd PATH] [--env KEY=VALUE] [--focus] [--no-focus]
+herdr pane swap --direction left|right|up|down [--pane ID|--current]
+herdr pane swap --source-pane ID --target-pane ID
+herdr pane move <pane_id> --tab <tab_id> --split right|down [--target-pane ID] [--ratio FLOAT] [--focus|--no-focus]
+herdr pane move <pane_id> --new-tab [--workspace ID] [--label TEXT] [--focus|--no-focus]
+herdr pane move <pane_id> --new-workspace [--label TEXT] [--tab-label TEXT] [--focus|--no-focus]
+herdr pane close <pane_id>
+```
+
+出力を読む:
+
+```bash
+herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N]
+herdr pane read <pane_id> --source visible --ansi
+herdr pane read <pane_id> --source recent-unwrapped --lines 120
+```
+
+入力を送る:
+
+```bash
+herdr pane send-text <pane_id> <text>
+herdr pane send-keys <pane_id> <key> [key ...]
+herdr pane run <pane_id> <command>
+```
+
+`<key>` は Herdr のキーコンボ構文を使います: `a` のような通常の印字可能キー、`enter`、`tab`、`esc`、`backspace`、`left`、`right`、`up`、`down` のような特殊キー、`ctrl+h`、`control+j`、`alt+x`、`shift+tab` のような修飾キーコード、`f1` のようなファンクションキー、そして `minus`、`plus`、`backtick` のような名前付き記号です。レガシーな `C-c` と `c-c` は `ctrl+c` のエイリアスとして受け付けられます。
+
+`pane run` はテキストと Enter をアトミックに送信します。コマンドには `send-text` + `send-keys Enter` よりこちらを使ってください。
+
+カスタムフックからエージェント状態を報告する:
+
+```bash
+herdr pane report-agent <pane_id> \
+ --source ID \
+ --agent LABEL \
+ --state idle|working|blocked|unknown \
+ [--message TEXT] \
+ [--custom-status TEXT] \
+ [--seq N] \
+ [--agent-session-id ID] \
+ [--agent-session-path PATH]
+```
+
+公式インテグレーションがネイティブセッション参照を報告している場合、`pane get`、`pane list`、`agent get`、`agent list` は読み取り専用の `agent_session` オブジェクトを含みます。ネイティブセッション参照が保存されていない場合、このフィールドは省略されます。
+
+これらのコマンドは、ペインを制御しているフォアグラウンドプロセスの cwd を解決できる場合に `foreground_cwd` を含みます。既存の `cwd` フィールドは、ラベルと follow-cwd 挙動に使われるペイン/ワークスペースの cwd のままです。
+
+意味的な状態を奪わずに、表示専用のペインメタデータを報告する:
+
+```bash
+herdr pane report-metadata <pane_id> \
+ --source ID \
+ [--agent LABEL] \
+ [--applies-to-source ID] \
+ [--title TEXT|--clear-title] \
+ [--display-agent TEXT|--clear-display-agent] \
+ [--custom-status TEXT|--clear-custom-status] \
+ [--state-label STATUS=TEXT] \
+ [--clear-state-labels] \
+ [--seq N] \
+ [--ttl-ms N]
+```
+
+`STATUS` は `idle`、`working`、`blocked`、`done`、`unknown` のいずれかです。`--agent` は権威あるエージェントラベルに対するガードです。`--applies-to-source` はアクティブなライフサイクル権威ソースに対するガードです。表示名を変えるには `--display-agent` を使ってください。
+
+メタデータのテキストは保存前に正規化されます。Herdr は前後の空白を取り除き、制御文字を除去し、`--custom-status` を 32 文字に、`--title`、`--display-agent`、各 `--state-label` の値を 80 文字に制限します。正規化後に空になった値は無視されます。
+
+`--source` と `--applies-to-source` は 80 文字以下で、ASCII の英字、数字、コロン、ドット、アンダースコア、ハイフンのみを含められます。`--ttl-ms` はメタデータを自動失効させ、`1` から `86400000` ミリ秒の間でなければなりません。置き換え・クリア・ペインのクローズまで残るべきメタデータでは省略してください。`--seq` により、Herdr は同じ `--source` からの古い報告を無視できます。古い報告は API には受理されますが、ペイン状態には無視されます。
+
+## エージェント
+
+```bash
+herdr agent list
+herdr agent get <target>
+herdr agent read <target> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi]
+herdr agent send <target> <text>
+herdr agent rename <target> <name>|--clear
+herdr agent focus <target>
+herdr agent wait <target> --status <idle|working|blocked|unknown> [--timeout MS]
+herdr agent attach <target> [--takeover]
+herdr agent start <name> [--cwd PATH] [--workspace ID] [--tab ID] [--split right|down] [--env KEY=VALUE] [--focus|--no-focus] -- <argv...>
+herdr agent explain <target> [--json|--verbose]
+herdr agent explain --file PATH --agent LABEL [--json|--verbose]
+```
+
+エージェントターゲットには、ターミナル ID、一意なエージェント名、検出または報告されたエージェントラベル、レガシーなペイン ID が使えます。名前とラベルはエージェントのアイデンティティです。ターミナル ID とレガシーペイン ID は低レベルな逃げ道です。
+
+`agent read` は解決されたターミナルストリームを読みます。`agent send` はそのストリームにリテラルのテキストを書き込みます。`agent get`、`agent focus`、`agent wait`、`agent attach` は、解決されたターミナルがエージェントのアイデンティティを持つことを要求します。`agent rename` はそのアイデンティティを割り当てられます。
+
+`agent explain` は、スクリーン検出が使うのと同じ下部バッファの検出スナップショットの分類を実行中のサーバーに依頼します。そのためライブの出力はサーバーのアクティブなマニフェストキャッシュを反映します。これは `agent.explain` ソケットメソッドを使うので、Herdr のアップグレード後にライブ explain を使う前に、サーバーを再起動するか更新済みサーバーへハンドオフしてください。保存済みフィクスチャをローカルで説明するには `--file PATH --agent LABEL` を使います。デフォルトの出力には、エージェント、最終状態、マニフェストのソースとバージョン、リージョンの証拠付きでマッチしたルール、そしてフォールバック・スキップ・警告の理由が表示されます。`--verbose` を付けると、可視の証拠フラグ、キャッシュされたリモートバージョン、ローカルオーバーライドのシャドーイング、リモート更新状況、マッチャーとリージョンの証拠付きの評価済みルール全リストが表示されます。issue の報告やテストには `--json` を付けてください。
+
+通常のターミナル、サーバー、テスト、シェル、低レベルなターミナル制御には `pane send-text`、`pane send-keys`、`pane run`、`terminal attach` を使ってください。Enter 付きでコマンドを送信したいときは `pane run` を使います。
+
+## ダイレクトターミナルアタッチ
+
+```bash
+herdr terminal attach <terminal_id> [--takeover]
+herdr terminal title set <title>
+herdr terminal title clear
+```
+
+ダイレクトアタッチからは `ctrl+b q` でデタッチします。リテラルの `ctrl+b` は `ctrl+b ctrl+b` で送ります。
+`terminal title clear` は Herdr のデフォルトの外側ターミナルウィンドウタイトルを復元します。
+
+## Wait
+
+ペインの出力を待つ:
+
+```bash
+herdr wait output <pane_id> --match <text> [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--regex] [--raw]
+```
+
+ペインのエージェント状態を待つ:
+
+```bash
+herdr wait agent-status <pane_id> --status <idle|working|blocked|done|unknown> [--timeout MS]
+```
+
+通常のコマンドやサーバーには `wait output` を使います。コーディングエージェントには `wait agent-status` を使います。
+
+## インテグレーション
+
+```bash
+herdr integration install pi
+herdr integration install omp
+herdr integration install claude
+herdr integration install codex
+herdr integration install copilot
+herdr integration install devin
+herdr integration install droid
+herdr integration install kimi
+herdr integration install opencode
+herdr integration install kilo
+herdr integration install hermes
+herdr integration install qodercli
+herdr integration install cursor
+herdr integration uninstall pi
+herdr integration uninstall omp
+herdr integration uninstall claude
+herdr integration uninstall codex
+herdr integration uninstall copilot
+herdr integration uninstall devin
+herdr integration uninstall droid
+herdr integration uninstall kimi
+herdr integration uninstall opencode
+herdr integration uninstall kilo
+herdr integration uninstall hermes
+herdr integration uninstall qodercli
+herdr integration uninstall cursor
+herdr integration status [--outdated-only]
+```
+
+## プラグイン
+
+プラグインコマンドは、ローカル実行型ワークフロープラグインをインストールして実行します。プラグインはマニフェストとプロセス外コマンドの組み合わせです。ホスト側の面は Herdr が、実装言語はプラグインが担います。
+
+プラグインのインストール、一覧、削除:
+
+```bash
+herdr plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]
+herdr plugin list [--plugin ID] [--json]
+herdr plugin uninstall <plugin_id|owner/repo[/subdir...]>
+herdr plugin enable <plugin_id>
+herdr plugin disable <plugin_id>
+```
+
+`plugin install` は `ogulcancelik/herdr-plugin-examples/worktree-bootstrap` のような GitHub 省略記法のみを受け付けます。`git` を使い、対話的なターミナルでは信頼プレビューを表示し、サポートされるマニフェストのビルドコマンドを実行し、GitHub インストールを Herdr 管理のディレクトリに保存します。非対話的なインストールには `--yes` を使ってください。GitHub 管理プラグインの再インストールは、その管理チェックアウトを置き換えます。ローカルにリンクされたプラグインへの上書きインストールは拒否されます。プラグインのマニフェストは `min_herdr_version` を宣言しなければならず、プラグインがより新しい Herdr バイナリを要求する場合、install と link は失敗します。`plugin list` はデフォルトで人間可読です。生の API レスポンスが欲しいときは `--json` を渡してください。
+
+ローカル開発:
+
+```bash
+herdr plugin link <path> [--disabled]
+herdr plugin unlink <plugin_id>
+```
+
+`plugin link` は `herdr-plugin.toml` を含むプラグインディレクトリ、またはマニフェストへの直接パスを受け付けます。ローカルチェックアウトからプラグインを作成・テストしている間はこれが正しいコマンドです。`plugin unlink` はプラグインの登録を解除し、ファイルには触れません。`plugin uninstall` はプラグインの登録を解除し、Herdr 管理の GitHub チェックアウトファイルも削除します。GitHub インストールの場合、uninstall はプラグイン id と、install で使うのと同じ `owner/repo[/subdir...]` 省略記法の両方を受け付けます。アクション、イベントフック、ペイン、リンクハンドラーはマニフェストで宣言します。ランタイムでのアクション登録は v1 の範囲外です。
+
+設定ディレクトリ:
+
+```bash
+herdr plugin config-dir <plugin_id>
+```
+
+`plugin config-dir` はプラグインの設定ディレクトリを表示し、必要なら作成します (レガシーなプラグイン設定の場所が存在すれば、そこから初期内容を移します)。セットアップドキュメントやシェルスクリプトで、管理されたプラグインチェックアウトとは別の、`.env` ファイルなどユーザーが編集する設定のための安定したパスをユーザーに示すのに使ってください。
+
+アクション:
+
+```bash
+herdr plugin action list [--plugin ID]
+herdr plugin action invoke <action_id> [--plugin ID]
+```
+
+`plugin action invoke` は、インストール済みで有効かつプラットフォーム互換のプラグインアクションのマニフェストコマンドを起動し、開始されたコマンドのログレコードを JSON レスポンスに表示します。複数のプラグインが同じアクション id を使っている場合は、修飾されたアクション id (`plugin.id.action`) を使ってください。ローカルのアクション id はドットを含められないため、プラグイン id がドットを含んでいても修飾 id は曖昧になりません。
+
+ログ:
+
+```bash
+herdr plugin log list [--plugin ID] [--limit N]
+```
+
+管理されたターミナルペイン:
+
+```bash
+herdr plugin pane open --plugin ID --entrypoint ID [--placement overlay|split|tab|zoomed] [--workspace ID] [--target-pane PANE] [--direction right|down] [--cwd PATH] [--env KEY=VALUE] [--focus|--no-focus]
+herdr plugin pane focus <pane_id>
+herdr plugin pane close <pane_id>
+```
+
+`plugin pane open` は、プラグインがリンクされ、有効で、現在のプラットフォームと互換であることを要求します。マニフェストで宣言された `[[panes]]` コマンドを Herdr 管理のターミナルペインとして起動します。マニフェストのデフォルトは `overlay` で、アクティブなペインの上に一時的なズームオーバーレイを開きます。分割、新しいタブ、ズームされたペインとして開くこともできます。ターミナル以外のネイティブなプラグインペインは今後の対応面です。
+
+`--env KEY=VALUE` はプロセスを起動するコマンドで繰り返し指定できます。新しく起動されるプロセスにのみ適用されます。`HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ENV`、`HERDR_WORKSPACE_ID`、`HERDR_TAB_ID`、`HERDR_PANE_ID`、`HERDR_PLUGIN_ID`、`HERDR_PLUGIN_ROOT`、`HERDR_PLUGIN_CONFIG_DIR`、`HERDR_PLUGIN_STATE_DIR`、`HERDR_PLUGIN_ENTRYPOINT_ID`、`HERDR_PLUGIN_CONTEXT_JSON` のような Herdr 管理の変数は、呼び出し側が与えた環境変数と衝突した場合も権威を保ちます。
+
+## 読み取りソース
+
+| ソース | 意味 |
+| --- | --- |
+| `visible` | 現在レンダリングされている画面。UI のフィードバックループに最適。 |
+| `recent` | ターミナルの折り返しを含む直近のスクロールバック。 |
+| `recent-unwrapped` | ソフト折り返しなしの直近のスクロールバック。ログに最適。 |
+| `detection` | エージェントのスクリーン検出が使う下部バッファのスナップショット。 |
+
+## 環境変数
+
+| 変数 | 目的 |
+| --- | --- |
+| `HERDR_CONFIG_PATH` | 設定ファイルパスを上書きする。 |
+| `HERDR_SESSION` | CLI コマンドの名前付きセッションを選択する。 |
+| `HERDR_SOCKET_PATH` | 低レベルなソケットパスの上書き。 |
+| `HERDR_ENV` | Herdr 管理のペインプロセス内で `1` に設定される。 |
+| `HERDR_PANE_ID` | 実行中ペインプロセスの公開ペイン id。 |
+| `HERDR_TAB_ID` | 実行中ペインプロセスの公開タブ id。 |
+| `HERDR_WORKSPACE_ID` | 実行中ペインプロセスの公開ワークスペース id。 |
+| `HERDR_LOG` | ログフィルターを設定する。例: `HERDR_LOG=herdr=debug`。 |
+| `HERDR_DISABLE_SOUND` | サウンド通知が有効でも音の再生を無効にする。 |
diff --git a/website/src/content/docs/ja/concepts.mdx b/website/src/content/docs/ja/concepts.mdx
new file mode 100644
index 00000000..640ba8a4
--- /dev/null
+++ b/website/src/content/docs/ja/concepts.mdx
@@ -0,0 +1,85 @@
+---
+title: コンセプト
+description: Herdr のワークスペース、タブ、ペイン、エージェント、セッション、モードを理解します。
+---
+
+Herdr はターミナルワークスペースマネージャーです。実際のターミナルプロセスを動かし続け、その周りに構造を加えます。
+
+## ワークスペース
+
+ワークスペースは最上位のプロジェクトコンテナです。リポジトリ、タスク、調査ごとにひとつのワークスペースを使ってください。
+
+ワークスペースはタブとペインを所有します。サイドバーの状態は内部のエージェントから集約されるので、どのプロジェクトが注意を必要としているかが分かります。
+
+## タブ
+
+タブはワークスペース内のレイアウトです。`agents`、`logs`、`server`、`review` のようにビューを分けるために使います。
+
+タブは CLI とソケット API からアドレス指定できます。
+
+## ペイン
+
+ペインは実際のターミナルです。Herdr はターミナル出力を描画し、入力をプロセスに送り返し、クライアントのデタッチ後もペインを維持します。
+
+ペインは右または下に分割できます。手動での名前変更、CLI からの読み取り、入力の送信、クローズができます。
+
+## マウス UI
+
+Herdr はマウスネイティブです。ペイン、タブ、ワークスペース、エージェントをクリックできます。分割境界のドラッグ、テキスト選択、右クリックメニューも使えます。以下で説明する操作はすべてマウスでも行えます。キーボードバインドは任意のレイヤーです。
+
+キーボードのみで操作したい場合や、Herdr にマウス入力をキャプチャさせたくない場合は、マウスキャプチャを無効にしてください:
+
+```toml
+[ui]
+mouse_capture = false
+```
+
+## エージェント
+
+エージェントは、Herdr がペイン内で認識するプロセスです。Herdr はフォアグラウンドプロセス、スクリーンマニフェスト、任意のインテグレーションからエージェントを検出します。
+
+エージェントの状態は次のとおりです:
+
+| 状態 | 意味 |
+| --- | --- |
+| `blocked` | エージェントが入力、承認、または判断を必要としている。 |
+| `working` | エージェントが実行中。 |
+| `done` | エージェントが完了し、まだ確認されていない。 |
+| `idle` | エージェントが完了または待機していて、確認済み。 |
+| `unknown` | Herdr が状態を確信を持って分類できない。 |
+
+## セッション
+
+セッションは永続的な Herdr サーバーの名前空間です。デフォルトの `herdr` コマンドはデフォルトセッションにアタッチします。
+
+名前付きセッションは独立したランタイム名前空間です:
+
+```bash
+herdr session list
+herdr session attach work
+herdr session attach side-project
+```
+
+まずはワークスペースを使ってください。ペイン、ソケット、永続化されたランタイム状態を完全に分離する必要があるときに名前付きセッションを使います。
+
+## クライアントとサーバー
+
+デフォルトでは、Herdr はバックグラウンドサーバーと、それにアタッチした 1 つ以上のクライアントとして動作します。
+
+サーバーはペインとプロセス状態を所有します。クライアントはそのサーバーにアタッチしたターミナル UI です。
+
+`ctrl+b q` でクライアントをデタッチします。サーバーとエージェントは動き続けます。
+
+セッションを終了してそのペインを停止したい場合は、サーバーを停止します:
+
+```bash
+herdr server stop
+```
+
+## モード
+
+Herdr にはターミナルモード、プレフィックスモード、ナビゲートモードがあります。
+
+ターミナルモードはフォーカス中のペインにキーを送ります。プレフィックスモードはプレフィックスキーの後に Herdr のアクションをひとつ待ちます。ナビゲートモードは常駐のワークスペースナビゲーション画面です。
+
+プレフィックスキー (デフォルト `ctrl+b`) を押してから、新しいタブなら `c`、ワークスペースナビゲーションなら `w` のようにアクションキーを押します。プレフィックスの考え方が初めてなら[キーボード](/ja/docs/keyboard/)を参照してください。
diff --git a/website/src/content/docs/ja/configuration.mdx b/website/src/content/docs/ja/configuration.mdx
new file mode 100644
index 00000000..39d3c825
--- /dev/null
+++ b/website/src/content/docs/ja/configuration.mdx
@@ -0,0 +1,526 @@
+---
+title: 設定
+description: Herdr のキーバインド、テーマ、サイドバーの挙動、通知、高度なオプションを設定します。
+---
+
+Herdr は設定ファイルなしで動作します。カスタムキー、テーマ、サイドバー設定、通知、高度な挙動が欲しくなったら追加してください。
+
+## 設定ファイル
+
+Herdr は次の場所から設定を読み込みます:
+
+```text
+~/.config/herdr/config.toml
+```
+
+完全なデフォルト設定を表示します:
+
+```bash
+herdr --default-config
+```
+
+完全な出発点が欲しい場合は、これを設定として保存してください:
+
+```bash
+herdr --default-config > ~/.config/herdr/config.toml
+```
+
+設定値が無効な場合、Herdr は安全なデフォルトにフォールバックし、起動時に警告を表示します。
+
+`onboarding` が存在しないか true の場合、Herdr は初回セットアップを表示します。オンボーディングから先へ進むと `onboarding = false` が書き込まれ、設定のインテグレーションタブが開きます。セットアップ後にそのフローをスキップしたい場合に設定してください。
+
+```toml
+onboarding = false
+```
+
+## アップデート
+
+Linux と macOS の直接インストールは、デフォルトで安定版アップデートチャンネルを使います。Windows ベータのインストールはデフォルトでプレビューを使い、安定版の Windows リリースが提供されるまで安定版には切り替えられません。
+
+```toml
+[update]
+channel = "stable"
+version_check = true
+manifest_check = true
+```
+
+`channel = "preview"` を設定すると、`herdr update` は現在の開発ブランチから手動公開されるプレビュービルドをインストールします。Homebrew、mise、Nix のインストールはプレビューチャンネルを無視し、それぞれのパッケージマネージャーでアップデートします。
+
+`version_check = false` を設定すると、新しい Herdr バージョンのバックグラウンドチェックを無効にします。手動の `herdr update` は引き続き設定済みチャンネルを使います。
+
+`manifest_check = false` を設定すると、リモートのエージェント検出マニフェストのバックグラウンドチェックを無効にします。Herdr はバンドルされたマニフェストとローカルオーバーライドを引き続き使います。
+
+## 設定のリロード
+
+`config.toml` を編集した後、実行中のサーバーをリロードします:
+
+```bash
+herdr server reload-config
+```
+
+Herdr のグローバルメニューを開いて `reload config` を選ぶこともできます。
+
+リロードは、ペインを再起動することなくほとんどの UI 設定を適用します。起動時のみの設定には引き続き再起動が必要です。
+
+## ターミナルのデフォルト
+
+新しく作成される対話的ペインに Herdr が使う実行ファイルを設定します:
+
+```toml
+[terminal]
+default_shell = "nu"
+```
+
+未設定または空の場合、Herdr は `$SHELL`、次に `/bin/sh` を使います。これは実行ファイル名またはパスであり、シェルのコマンドラインではありません。既存のペインは再作成されるまで現在のシェルを保ちます。コマンドペインは引き続き `/bin/sh -c` を通して実行され、デタッチされたカスタムコマンドキーバインドは Herdr の既存の `/bin/sh -lc` 経路を使います。
+
+新しく作成される対話的ペインのシェルの起動方法を設定します:
+
+```toml
+[terminal]
+shell_mode = "auto"
+```
+
+`shell_mode = "auto"` は macOS でログインシェルを起動するので、`/usr/libexec/path_helper` のようなログイン時のみの PATH 設定や Homebrew のシェル初期化が新しいペインで実行されます。他のプラットフォームでは既存の非ログインシェルの挙動を保ちます。ログインシェル起動を強制するには `"login"` を、オプトアウトするには `"non_login"` を使ってください。コマンドペイン、デタッチされたカスタムコマンドキーバインド、明示的な argv 起動は、既存のコマンド実行経路を保ちます。
+
+新しいペイン、タブ、ワークスペースの作業ディレクトリポリシーを設定します:
+
+```toml
+[terminal]
+new_cwd = "follow"
+```
+
+`new_cwd = "follow"` はデフォルトの挙動を保ち、元のペインまたはワークスペースを継承します。元のワークスペースがない場合、Herdr は `$HOME` で始めます。常に `$HOME` で始めるには `"home"` を、Herdr のプロセスディレクトリを使うには `"current"` を、または `"~/Projects"` のような固定パスを使ってください。CLI やソケット API からの明示的な `--cwd` 値は引き続き優先されます。
+
+## Worktree
+
+サイドバーから作成される Git worktree チェックアウトに Herdr が使うルートディレクトリを設定します:
+
+```toml
+[worktrees]
+directory = "~/.herdr/worktrees"
+```
+
+Herdr は `<directory>/<repo>/<branch-slug>` の下にチェックアウトを作成します。隣接ディレクトリ方式のチェックアウトにしたい場合は、`~/Projects/herdr-worktrees` のようなディレクトリを設定してください。相対値は、アプリが設定を適用する時点で絶対パスに解決されます。
+
+worktree アクションは Git ワークスペースの行から使えます。`New worktree` はチェックアウトを作成し、入力されたブランチが既存なら既存のローカルブランチをチェックアウトし、なければブランチを作成し、新しい Herdr ワークスペースとして開き、元のワークスペースの下にグループ化します。`Open worktree...` はそのリポジトリの既存の Git worktree チェックアウトを一覧します。すでに開いているチェックアウトを選ぶとフォーカスし、閉じているチェックアウトを選ぶと同じグループで開きます。
+
+グループ化された worktree も通常の Herdr ワークスペースと同じように振る舞います: フォーカス、名前変更、クローズができ、独自のタブとペインを持ちます。親の行は元のワークスペースです。親の行を閉じると Herdr のグループ全体が閉じますが、チェックアウトのフォルダーやブランチは削除されません。
+
+worktree チェックアウトの削除は明示的です。グループ化された子ワークスペースで `Delete worktree checkout...` を使うと `git worktree remove` が実行されます。Herdr はまず Git に安全な削除を依頼します。チェックアウトに変更済みまたは未追跡のファイルがあって Git が拒否した場合、Herdr は強制削除を実行する前にもう一度確認します。ブランチは削除されません。
+
+## リモートアタッチ
+
+リモートアタッチは、デフォルトで一時的なキープアライブフォールバック付きの SSH ブリッジを管理します。
+
+```toml
+[remote]
+manage_ssh_config = true
+```
+
+有効な場合、`herdr --remote` はあなたの `~/.ssh/config` と `/etc/ssh/ssh_config` を最初に include し、その後にフォールバックの `ServerAliveInterval` と `ServerAliveCountMax` の値を加えたプライベートな一時 SSH 設定を書き込みます。あなた自身の SSH キープアライブ設定が優先されます。Herdr が生成する設定を使わず素の `ssh` でブリッジを実行するには `manage_ssh_config = false` を設定してください。
+
+## キーバインド
+
+プレフィックスの導入ガイドと検証済みのプレフィックスなし構成については、[キーボード](/ja/docs/keyboard/)を参照してください。
+
+Herdr には tmux に似たプレフィックスモードがあります。デフォルトのプレフィックスは `ctrl+b` です。キーバインド文字列は明示的です: `prefix+n` は設定されたプレフィックスを押してから `n` を押すという意味で、`ctrl+alt+n` はターミナルモードの直接ショートカットです。
+
+小さなキーバインドの上書きは次のようになります:
+
+```toml
+[keys]
+prefix = "ctrl+b"
+goto = "prefix+g"
+new_tab = "prefix+c"
+next_tab = "prefix+n"
+previous_tab = "prefix+p"
+focus_pane_left = "prefix+h"
+navigate_workspace_down = "j"
+navigate_pane_down = "ctrl+j"
+split_horizontal = "prefix+minus"
+```
+
+デフォルトのキーマップはプレフィックス優先で、シェル、エディタ、tmux、ターミナルアプリから入力を奪いうる直接ショートカットを避けています。主なデフォルトは次のとおりです:
+
+```toml
+[keys]
+detach = "prefix+q"
+workspace_picker = "prefix+w"
+goto = "prefix+g"
+new_workspace = "prefix+shift+n"
+new_worktree = "prefix+shift+g"
+rename_workspace = "prefix+shift+w"
+close_workspace = "prefix+shift+d"
+navigate_workspace_up = "up"
+navigate_workspace_down = "down"
+navigate_pane_left = "h"
+navigate_pane_down = "j"
+navigate_pane_up = "k"
+navigate_pane_right = "l"
+remote_image_paste = "ctrl+v"
+new_tab = "prefix+c"
+previous_tab = "prefix+p"
+next_tab = "prefix+n"
+switch_tab = "prefix+1..9"
+rename_tab = "prefix+shift+t"
+close_tab = "prefix+shift+x"
+copy_mode = "prefix+["
+focus_pane_left = "prefix+h"
+focus_pane_down = "prefix+j"
+focus_pane_up = "prefix+k"
+focus_pane_right = "prefix+l"
+swap_pane_left = "prefix+shift+h"
+swap_pane_down = "prefix+shift+j"
+swap_pane_up = "prefix+shift+k"
+swap_pane_right = "prefix+shift+l"
+cycle_pane_next = "prefix+tab"
+cycle_pane_previous = "prefix+shift+tab"
+last_pane = ""
+split_vertical = "prefix+v"
+split_horizontal = "prefix+minus"
+close_pane = "prefix+x"
+zoom = "prefix+z"
+resize_mode = "prefix+r"
+toggle_sidebar = "prefix+b"
+```
+
+任意のアクションはデフォルトでは未設定です。プレフィックスモードの挙動には `prefix+` で、意図的に直接ショートカットにしたいときは明示的な修飾キーコードでバインドしてください:
+
+```toml
+[keys]
+previous_workspace = "prefix+shift+left"
+next_workspace = "prefix+shift+right"
+last_pane = "prefix+tab"
+open_worktree = "prefix+shift+o"
+remove_worktree = "prefix+alt+d"
+next_tab = ["prefix+n", "ctrl+alt+]"]
+```
+
+`last_pane` はワークスペースとタブをまたいで最後にフォーカスしていたペインに戻ります。tmux スタイルのペインバインド `prefix+l` がすでに右のペインへのフォーカスに使われているため、デフォルトでは未設定です。
+
+`remote_image_paste` は `herdr --remote` でのみ有効です。ローカルのクリップボード画像をリモートのペインに送るローカルクライアント側のショートカットです。空文字列に設定すると生キーのショートカットを無効にできます。外側のターミナルが送る paste-image シグナルは引き続き機能します。
+
+キー文字列には、通常のキー、`ctrl+a`、`shift+n`、`alt+1`、`cmd+k` のような修飾キーの組み合わせ、`enter`、`tab`、`esc`、`left`、`right`、`up`、`down` のような特殊キーが使えます。`minus`、`comma`、`ampersand`、`plus`、`backtick` のような名前付き記号も受け付けます。`n` のような通常の印字可能キーの直接バインドはタイピングを妨げるため危険です。意図的に直接バインドしたいのでなければ `prefix+n` を使ってください。`navigate_workspace_*` と `navigate_pane_*` のフィールドはナビゲートモード専用で、`j` や `k` のような通常のキーを使えます。これらには `prefix+`、`esc`、`enter`、`tab`、`shift+tab`、`left`、`right`、修飾なしの `1` から `9` は使えません。左右の矢印キーは、左ペイン/右ペインナビゲーションの恒久的なエイリアスです。これらのナビゲートモードショートカットは `focus_pane_down = "prefix+j"` のような一般アクションバインドから独立しています。両方が同じキーを使う場合、ナビゲートモードが開いている間はナビゲートモードのショートカットが優先されます。Alt、Cmd/Super、修飾キー付き記号はターミナルと tmux の設定に依存します。
+
+古いカスタムキーバインドを持っていて新しいデフォルトが欲しい場合は、`herdr config reset-keys` を実行してください。Herdr は `config.toml` をバックアップし、`[keys]` と `[[keys.command]]` を削除し、再起動または `herdr server reload-config` の後に組み込みの v2 デフォルトを使います。
+
+## インデックス付きジャンプ
+
+インデックス付きキーバインドは、通常のキーバインドフィールドで `1..9` を使います:
+
+```toml
+[keys]
+switch_tab = "prefix+1..9"
+switch_workspace = "prefix+shift+1..9"
+focus_agent = "prefix+alt+1..9"
+```
+
+レガシーな `[keys.indexed]` テーブルは互換性のために引き続きパースされますが、新しい設定では明示的なアクションフィールドを使ってください。
+
+## カスタムコマンドキーバインド
+
+カスタムコマンドも同じキーバインド構文を使います。
+
+```toml
+[[keys.command]]
+key = "prefix+alt+g"
+type = "pane"
+command = "lazygit"
+description = "run lazygit"
+```
+
+`type = "pane"` は一時的なペインを開き、コマンドの終了時に閉じます。
+
+`type = "shell"` はバックグラウンドでデタッチ実行します。
+
+`type = "plugin_action"` はインストール済みプラグインのアクション id を呼び出します。アクション id がグローバルに一意でない場合は修飾 id を使ってください:
+
+```toml
+[[keys.command]]
+key = "prefix+l"
+type = "plugin_action"
+command = "example.layout.apply"
+description = "apply layout"
+```
+
+任意で `description` を指定できます。指定すると、キーバインドヘルプパネル (`prefix+?` で開く) にデフォルトの `'custom command'` ラベルの代わりに表示されます。
+
+カスタムコマンドは、利用可能な場合に `HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ACTIVE_WORKSPACE_ID`、`HERDR_ACTIVE_TAB_ID`、`HERDR_ACTIVE_PANE_ID`、`HERDR_ACTIVE_PANE_CWD` を受け取ります。シェルコマンドは、Herdr が検出できる場合、フォーカス中のペインの作業ディレクトリから実行されます。
+
+## テーマ
+
+組み込みテーマを選びます:
+
+```toml
+[theme]
+name = "catppuccin"
+```
+
+組み込みテーマ:
+
+`catppuccin`、`catppuccin-latte`、`terminal`、`tokyo-night`、`tokyo-night-day`、`dracula`、`nord`、`gruvbox`、`gruvbox-light`、`one-dark`、`one-light`、`solarized`、`solarized-light`、`kanagawa`、`kanagawa-lotus`、`rose-pine`、`rose-pine-dawn`、`vesper`。
+
+Herdr の UI 色をホストターミナルの ANSI パレットに従わせたいときは `terminal` を使ってください。
+
+ホストターミナルがライト/ダークの外観変更を報告したときに Herdr が自分の UI テーマを切り替えるようにするには、テーマの自動切り替えを有効にします:
+
+```toml
+[theme]
+name = "catppuccin"
+auto_switch = true
+light_name = "catppuccin-latte"
+dark_name = "catppuccin"
+```
+
+`auto_switch` のデフォルトは `false` なので、既存のテーマ設定は手動の挙動を保ちます。`light_name` または `dark_name` を省略すると、Herdr は設定された `name` に対応する組み込みの姉妹テーマが存在すればそれを使います (例: `tokyo-night`/`tokyo-night-day`、`gruvbox`/`gruvbox-light`)。設定画面での手動のテーマ選択は `auto_switch` を無効にします。
+
+個々の色を上書きできます:
+
+```toml
+[theme.custom]
+panel_bg = "reset"
+accent = "#a6e3a1"
+green = "#a6e3a1"
+blue = "#89b4fa"
+red = "#f38ba8"
+yellow = "#f9e2af"
+```
+
+色の値には、hex、名前付きの色、`rgb(r,g,b)`、または `reset`、`default`、`none`、`transparent` のようなリセットエイリアスが使えます。
+
+## UI とサイドバー
+
+サイドバーは Herdr のメインダッシュボードです。ワークスペース、タブ、ペイン、エージェントの状態を表示します。
+
+主なオプション:
+
+```toml
+[ui]
+sidebar_width = 32
+sidebar_min_width = 18
+sidebar_max_width = 36
+mobile_width_threshold = 64
+mouse_capture = true
+right_click_passthrough_modifier = ""
+redraw_on_focus_gained = true
+mouse_scroll_lines = 3
+confirm_close = true
+prompt_new_tab_name = true
+pane_borders = true
+pane_gaps = true
+show_agent_labels_on_pane_borders = false
+agent_panel_sort = "spaces"
+accent = "cyan"
+```
+
+`sidebar_min_width` と `sidebar_max_width` は、展開されたサイドバーのリサイズ範囲を桁数で制御します。デフォルトは 18 と 36 です。
+
+`mobile_width_threshold` は、Herdr がモバイル向けの単一カラムレイアウトを使うターミナル幅の閾値を制御します。デフォルトは 64 桁です。折りたたみ端末、タブレット、幅の広いスマートフォンターミナルでは増やしてください。
+
+エージェントパネルはすべてのスペースをまたいですべてのエージェントを表示します。`agent_panel_sort` には `spaces` または `priority` を指定できます。`workspaces` は `spaces` のエイリアスとして受け付けられます。デフォルトは `spaces` で、エージェントをスペース順にグループ化したまま保ちます。`priority` は注意の優先度順に並べます: blocked、done、working、idle、そして unknown です。同じステータス内では、最近状態が変わったエージェントが先に表示されます。
+
+`confirm_close` はワークスペースを閉じるときに確認を求めるかどうかを制御します。`prompt_new_tab_name` は新しいタブで先にラベルを尋ねるかどうかを制御します。
+
+URL の command+クリックなど、通常のクリックをターミナルに処理させたい場合は `mouse_capture = false` を設定してください。マウスキャプチャが有効な場合、ターミナルが修飾キー付きクリックを Herdr に送れば、Ctrl+クリックでペインのリンクを開けます。これは macOS も含みます。Herdr がマウス入力をキャプチャしている間、Cmd+クリックは通常のクリックと区別して報告されません。ターミナルネイティブのバイパス経路には、Linux では Shift+Ctrl+クリック、macOS では Shift+Cmd+クリックを使ってください。
+
+マウスレポーティング対応のペインアプリの中で、Ctrl+右クリック、ホールド、ドラッグのジェスチャーを Herdr のペインメニューを開く代わりにアプリへ届けたい場合は `right_click_passthrough_modifier = "ctrl"` を設定してください。デフォルトは空で、このパススルーは無効です。対応する修飾キーは `ctrl`、`alt`、`cmd`、`super`、`meta`、`hyper` です。多くのターミナルが Shift+マウスを自分のマウスバイパスのために予約しているため、`shift` は拒否されます。
+
+Herdr に戻ったときの目に見える全画面リフレッシュを避けるには `redraw_on_focus_gained = false` を設定してください。まれに発生する古い/汚れたホストターミナル表示から全再描画で回復できるため、デフォルトは `true` です。
+
+マウスホイール 1 ノッチでスクロールするペインのスクロールバック行数を変えるには `mouse_scroll_lines` を設定します。デフォルトは 3 です。マウスレポーティングを要求するペインアプリは引き続きホイールイベントを直接受け取ります。オルタネートスクリーンのアプリにはスクロールするスクロールバックがありません。[スクロールバック](#スクロールバック)を参照してください。
+
+分割ペインの境界線を消すには `pane_borders = false` を設定します。分割ペインにコンパクトな共有仕切り線を使わせるには `pane_gaps = false` を設定します。境界線が無効な場合、ペインの間隔はペイン間の空白ターミナルセル 1 個になります。ターミナルのセルは通常、幅より高さが大きいため、上下ペイン間の 1 行の間隔は左右ペイン間の 1 桁の間隔より大きく見えることがあります。
+
+手動のペインラベルが設定されていないときに、検出されたエージェントラベルを分割ペインの境界線に表示したい場合は `show_agent_labels_on_pane_borders = true` を設定してください。
+
+## 通知
+
+Herdr は、エージェントが完了したり入力を必要としたりしたときにポップアップ通知を表示できます。
+
+```toml
+[ui.toast]
+delivery = "off"
+delay_seconds = 1
+
+[ui.toast.herdr]
+position = "bottom-right"
+
+[ui.toast.clipboard]
+enabled = true
+position = "bottom-center"
+```
+
+`delivery = "off"` はポップアップ通知を無効にします。これがデフォルトです。
+
+`delivery = "herdr"` は Herdr の UI 内にトーストを表示します。トーストをクリックするか、`keys.open_notification_target` をバインドすると、対象のワークスペース、タブ、ペインにフォーカスします。`ui.toast.herdr.position` には `top-left`、`top-right`、`bottom-left`、`bottom-right` を設定できます。デスクトップの位置は Herdr のフレーム全体を基準とします。
+
+`delivery = "terminal"` は外側のターミナルにデスクトップ通知の表示を依頼します。Herdr は Ghostty、iTerm2、Kitty、WezTerm 向けのターミナル通知エスケープシーケンスを送ります。ローカルのターミナルが通知を所有するため、SSH 越しで便利です。
+
+`delivery = "system"` はローカルのオペレーティングシステムに直接依頼します。macOS では、Herdr は `terminal-notifier` が利用可能ならそれを使い、なければ `/usr/bin/osascript` にフォールバックします。`terminal-notifier` は通知をクリックしたときにホストのターミナルをアクティブにできます。Linux では、Herdr は `notify-send` を使い、`DISPLAY` または `WAYLAND_DISPLAY` を必要とします。
+
+ポップアップ通知はバックグラウンドの注意喚起のためのものです。Herdr はアクティブなタブについてはポップアップを抑制します。
+
+`delay_seconds` は、完了または入力要求のエージェント通知を送る前に待機します。Herdr は、遅延が切れた時点でペインがまだ同じ状態の場合にのみ通知します。即時通知には `0` を設定してください。有効な値は `0` から `3600` です。
+
+クリップボードのフィードバックは、フォアグラウンドのコピー操作を確認するもので、terminal や system の配信では送られないため、別に設定します。コピー完了のポップアップを隠すには `ui.toast.clipboard.enabled = false` を設定してください。クリップボードの位置は `top-left`、`top-center`、`top-right`、`bottom-left`、`bottom-center`、`bottom-right` です。
+
+## サウンド
+
+サウンド通知はデフォルトで有効で、ローカルの Herdr クライアントが再生します。
+
+```toml
+[ui.sound]
+enabled = true
+```
+
+Herdr は、エージェントが完了したときに完了音を、エージェントが入力を必要とするときに注意音を再生します。共有マシンやリモートサーバーでは、明示的に音が欲しいのでなければ `enabled = false` を設定してください。
+
+macOS では、Herdr は `afplay` を使います。Linux では、mp3 対応プレイヤーを順に試します: `paplay`、`pw-play`、`ffplay`、`mpg123`、そして `mpv` です。プレイヤーがない場合、音の再生はスキップされ、Herdr は警告をログに残します。
+
+カスタムサウンドは mp3 ファイルでなければなりません。相対パスは設定ファイルのディレクトリから解決されます。
+
+```toml
+[ui.sound]
+path = "sounds/notification.mp3"
+done_path = "sounds/done.mp3"
+request_path = "sounds/request.mp3"
+```
+
+`path` はすべてのサウンド通知にひとつの音を設定します。`done_path` と `request_path` は、完了音と入力要求音だけを上書きします。
+
+エージェント別のサウンド上書きには `default`、`on`、`off` を指定できます。キーには `claude`、`codex`、`devin`、`droid` のような検出されたエージェントラベルを使います。Droid はデフォルトでミュートされています。
+
+```toml
+[ui.sound.agents]
+droid = "off"
+claude = "on"
+```
+
+## スクロールバック
+
+新しく作成されるペインのスクロールバックバッファサイズを設定します:
+
+```toml
+[advanced]
+scrollback_limit_bytes = 10485760
+```
+
+既存のペインは、再作成されるまで現在のバッファを保ちます。
+
+ペインは、アプリがプライマリスクリーンに書き込んでいるときにのみスクロールバーを表示します。オルタネートスクリーンに切り替えるフルスクリーンアプリ (vim、htop、`CLAUDE_CODE_NO_FLICKER=1` の Claude Code) はスクロールバックを生成しないため、スクロールバーは表示されず、ホイールイベントはアプリに直接ルーティングされます。アプリ自身のキーや UI でスクロールしてください。
+
+## ペイン画面履歴
+
+デフォルトでは、セッションの完全な再起動はワークスペース、タブ、ペイン、cwd、レイアウト、フォーカスを、ペインの内容を保存せずに復元します。
+
+ペイン画面履歴はデフォルトで無効です。ペイン出力にはシークレット、トークン、プロンプト、コマンド出力が含まれうるため、サーバーの完全な再起動をまたいで Herdr に直近のペイン内容を保存させたいときだけ有効にしてください:
+
+```toml
+[experimental]
+pane_history = true
+```
+
+Settings > Experiments > pane screen history からも切り替えられます。
+
+有効にすると、Herdr は保存したペイン履歴を `session.json` の隣の `session-history.json` に保存します。
+
+ペイン画面履歴が、ライブ永続化、スナップショット復元、エージェントネイティブのセッション復元、ライブハンドオフとどう違うかは[セッション状態と復元](/ja/docs/session-state/)を参照してください。
+
+## ネストされた起動
+
+Herdr は通常、Herdr の中で Herdr を起動しないよう保護しています。
+
+```toml
+[experimental]
+allow_nested = false
+```
+
+ネストされた起動はテスト目的でのみ有効にしてください。
+
+## Kitty graphics
+
+Kitty graphics のサポートは実験的です。
+
+```toml
+[experimental]
+kitty_graphics = false
+```
+
+ターミナルの画像挙動をテストしているのでなければ無効のままにしてください。
+
+## エージェントセッション復元
+
+Herdr は、Herdr サーバーの再起動後に、対応エージェントのペインをネイティブの会話セッションで再起動できます。
+
+```toml
+[session]
+resume_agents_on_restore = true
+```
+
+これはデフォルトで有効です。Herdr が resume するのは、公式 Herdr インテグレーションを通じてネイティブセッション参照を報告したペインだけです。対応する resume ターゲットは Claude Code、Codex、Cursor Agent CLI、GitHub Copilot CLI、Droid、Kimi Code CLI、Qoder CLI、Pi、Hermes Agent、OpenCode、Kilo Code CLI です。未対応、欠落、無効、重複、または古くなったセッション参照は、保存されたペインディレクトリで通常のシェルとして復元されます。
+
+セッション参照はローカルの Herdr セッションスナップショットに保存されます。通常のペイン、エージェント、ステータス、イベント出力には表示されません。
+
+エージェントネイティブのセッション復元が、ペイン画面履歴やライブハンドオフとどう違うかは[セッション状態と復元](/ja/docs/session-state/)を参照してください。
+
+## IME カーソルトラッキング
+
+フォーカス中のペインがカーソルを隠して独自に描画する場合 — Claude Code、pi、codex、Devin のような AI エージェント TUI でよくあります — 外側のターミナルがカーソルを報告しなくなるため、macOS のネイティブ入力メソッドは変換候補ウィンドウの位置を追跡できなくなります。
+
+ペインの `?25l` 要求に関係なく、フォーカス中のペインのカーソルアンカーを外側のターミナルに公開するには `reveal_hidden_cursor_for_cjk_ime = true` を設定します:
+
+```toml
+[experimental]
+reveal_hidden_cursor_for_cjk_ime = false
+cjk_ime_agents = []
+cjk_ime_cursor_shape = "steady_block"
+```
+
+有効にすると、カーソルはフォーカス中のペインが報告した位置に表示され続けます。ペインがカーソル位置を報告しない場合、アンカーはペインの左上にフォールバックし、安定した IME ヒントが常に利用できます。
+
+`cjk_ime_agents` は任意の許可リストです。空の場合、この表示はどのフォーカス中ペインにも適用されます。空でない場合、フォーカス中ペインの検出エージェントがリスト内の名前のいずれかに一致するときだけ適用されます — 独自にカーソルを描画する AI エージェント TUI でのみ有効にして、素のシェルには影響を与えたくないときに便利です。受け付ける名前: `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli`、`qoder`。不明な名前は無視されます。リストに有効な名前がひとつもない場合、この表示は適用されません。
+
+`cjk_ime_cursor_shape` は IME アンカー用に描画される DECSCUSR の形状を制御します。受け付ける値: `block`、`steady_block` (デフォルト)、`underline`、`steady_underline`、`bar`、`steady_bar`。
+
+既存の `[experimental]` ブロックを通じてホットリロードされます。
+
+有効時のトレードオフ: 代わりのカーソルを描画せずにカーソルを隠すアプリ (vim のノーマルモードなど) では、外側のターミナルに余分なハードウェアカーソルが表示されます。特定の TUI に絞るには `cjk_ime_agents` と組み合わせてください。
+
+## プレフィックスでの入力ソース切り替え
+
+macOS では、非 ASCII の入力ソースがアクティブな間、プレフィックスコマンドがホストの入力ソースを通して解釈されるため、プレフィックスモードのコマンドが使いにくいことがあります。
+
+プレフィックスモードがアクティブな間、ホストの入力ソースをシステムの ASCII 対応入力ソースに切り替えるには `switch_ascii_input_source_in_prefix = true` を設定します:
+
+```toml
+[experimental]
+switch_ascii_input_source_in_prefix = false
+```
+
+有効にすると、Herdr はプレフィックスモードに入った後にのみ入力ソースを切り替え、プレフィックスモードの終了時に以前の入力ソースを復元します。この設定は macOS 専用で、他のプラットフォームやシステムの入力ソース切り替えが失敗した場合は何もしません。
+
+Settings > Experiments > switch to ascii input source in prefix (macOS) からも切り替えられます。
+
+## 環境変数
+
+| 変数 | 目的 |
+| --- | --- |
+| `HERDR_CONFIG_PATH` | 設定ファイルパスを上書きする。 |
+| `HERDR_SESSION` | CLI コマンドの名前付きセッションを選択する。 |
+| `HERDR_SOCKET_PATH` | 低レベルなソケットパスの上書き。 |
+| `HERDR_LOG` | ログフィルタリングを設定する。例: `HERDR_LOG=herdr=debug`。 |
+| `HERDR_DISABLE_SOUND` | `[ui.sound] enabled = true` でも音の再生を無効にする。 |
+
+## ログ
+
+ログは、起動時の警告、インテグレーションの状態、ソケット API の挙動を診断するときに便利です。
+
+主なログファイル:
+
+```text
+~/.config/herdr/herdr.log
+~/.config/herdr/herdr-client.log
+~/.config/herdr/herdr-server.log
+```
+
+ログは自動的にローテーションされます。問題を報告するときは、現在のログとローテーションされたファイルを含めてください。
diff --git a/website/src/content/docs/ja/how-to-work.mdx b/website/src/content/docs/ja/how-to-work.mdx
new file mode 100644
index 00000000..0365df0b
--- /dev/null
+++ b/website/src/content/docs/ja/how-to-work.mdx
@@ -0,0 +1,103 @@
+---
+title: Herdr での作業の進め方
+description: Herdr をローカルで、SSH 内で、またはリモートアタッチで使います。
+---
+
+Herdr は作業がある場所で動かし、どこからでもアタッチします。
+
+Herdr はバックグラウンドのセッションサーバーと、1 つ以上のターミナルクライアントで構成されます。ペインはサーバー内で動き続けます。クライアントはアタッチ、デタッチし、セッションを描画します。
+
+## ローカルでの作業
+
+プロジェクトディレクトリから Herdr を起動します:
+
+```bash
+herdr
+```
+
+Herdr はローカルのバックグラウンドセッションを自動的に起動するか、それにアタッチします。ソケットを管理する必要はありません。ペインの中でシェル、サーバー、テスト、エージェントを普段どおり実行してください。
+
+`ctrl+b q` でクライアントをデタッチします。ペインは動き続けます。
+
+あとで再アタッチします:
+
+```bash
+herdr
+```
+
+セッションを終了してペインを停止したい場合は、サーバーを停止します:
+
+```bash
+herdr server stop
+```
+
+## 通常の SSH 越しのリモート作業
+
+コードと認証情報のあるマシンに SSH して、そこで Herdr を実行します:
+
+```bash
+ssh you@server
+herdr
+```
+
+これはターミナルマルチプレクサと同じように動作します。シェルはリモート、Herdr サーバーもリモート、エージェントとペインはリモートマシン上で動きます。`ctrl+b q` でデタッチして切断し、あとで SSH し直して再び `herdr` を実行してください。
+
+すでに SSH シェルの中で作業している場合、スマートフォンやタブレットの SSH クライアントを使っている場合、あるいは最もシンプルな構成にしたい場合はこの方法を使ってください。
+
+## スマートフォンから作業する
+
+Herdr のモバイルアプリや Web ダッシュボードは不要です。スマートフォンに任意の SSH クライアントを入れ、エージェントが動いているマシンに接続して、そこで Herdr を起動するだけです:
+
+```bash
+ssh you@server
+herdr
+```
+
+同じ永続 Herdr セッションがスマートフォンのターミナルに開きます。TUI は狭い画面に適応するので、SSH から離れることなくエージェントの確認、ワークスペースの切り替え、ペインのチェックができます。
+
+iPhone では [moshi](https://getmoshi.app/) のようなアプリがよく動作します。
+
+<div class="mobile-doc-shots">
+ <figure>
+ <img src="/assets/mobile-agent-session-v2.jpeg" alt="スマートフォンで SSH 越しに表示した Herdr のエージェントセッション" loading="lazy" />
+ <figcaption>SSH 越しのエージェントセッション</figcaption>
+ </figure>
+ <figure>
+ <img src="/assets/mobile-switch-menu-v2.jpeg" alt="スマートフォンで表示した Herdr のレスポンシブ切り替えメニュー" loading="lazy" />
+ <figcaption>レスポンシブな切り替えメニュー</figcaption>
+ </figure>
+</div>
+
+## ローカルターミナルからのリモート作業
+
+先にシェルを開かずに SSH 越しでアタッチします:
+
+```bash
+herdr --remote workbox
+herdr --remote ssh://you@server:2222
+```
+
+ローカルの Herdr はシンクライアントとして動作します。SSH 越しに接続し、リモートの Herdr サーバーを起動またはアタッチして、UI をローカルターミナルにストリーミングします。
+
+リモートセッションをローカルのように感じたいときはこの方法を使ってください。クライアントは手元のマシンで動くので、画像クリップボードの貼り付けのようなローカルデスクトップ機能をリモートサーバーにブリッジできます。先に SSH してサーバー上で `herdr` を実行した場合、Herdr は完全にそのサーバー上で動くため、ローカルデスクトップのクリップボードは読めません。
+
+繰り返し接続する相手は SSH config に登録しておきましょう:
+
+```text
+Host workbox
+ HostName server.example.com
+ User you
+ Port 2222
+```
+
+その後はこれでアタッチできます:
+
+```bash
+herdr --remote workbox
+```
+
+## どの方法を使うか
+
+ローカル作業には `herdr` を使います。リモートシェル上で Herdr を tmux のように使いたいときや、スマートフォンの SSH クライアントを使っているときは `ssh you@server` してから `herdr` を使います。リモートセッション用のローカルシンクライアントが欲しいとき (ローカルクリップボードの画像貼り付けブリッジを含む) は `herdr --remote <host>` を使います。
+
+リモートブートストラップの詳細、名前付きリモートセッション、カスタムバイナリ、ダイレクトターミナルアタッチ、`--no-session` については[永続化とリモートアクセス](/ja/docs/persistence-remote/)を参照してください。
diff --git a/website/src/content/docs/ja/index.mdx b/website/src/content/docs/ja/index.mdx
new file mode 100644
index 00000000..ce26d5fb
--- /dev/null
+++ b/website/src/content/docs/ja/index.mdx
@@ -0,0 +1,77 @@
+---
+title: Herdr ドキュメント
+description: AI コーディングエージェントのためのターミナルワークスペースマネージャー。
+template: splash
+hero:
+ tagline: "Herdr のインストール、学習、設定。あなたに合ったパスから始めましょう — マルチプレクサの経験は不要です。"
+ image:
+ file: ../../../../public/assets/logo.svg
+ actions:
+ - text: Herdr をインストール
+ link: /ja/docs/install/
+ - text: クイックスタート
+ link: /ja/docs/quick-start/
+ variant: secondary
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+## パスを選ぶ
+
+<CardGrid>
+ <Card title="ターミナルマルチプレクサは初めて?">
+ ショートカットを覚えなくても始められます。Herdr はマウスファーストです。ペインをクリックし、境界をドラッグし、右クリックメニューから分割や切り替えができます。
+
+ [クイックスタート →](/ja/docs/quick-start/)
+ </Card>
+ <Card title="tmux や zellij から乗り換え?">
+ モデルはすでにご存じのとおりです。プレフィックスは `ctrl+b`、ペインは永続化され、デタッチと再アタッチは期待どおりに動作します。
+
+ [コンセプト →](/ja/docs/concepts/) · [キーバインド →](/ja/docs/configuration/#キーバインド)
+ </Card>
+</CardGrid>
+
+## またはエージェントに案内してもらう
+
+すでに AI コーディングエージェントを使っていますか? オンボーディングはエージェントに任せましょう。このプロンプトを貼り付けてください:
+
+```text
+Help me understand and set up Herdr. Read https://herdr.dev/agent-guide.md first, then walk me through it step by step.
+```
+
+このガイドはエージェントに Herdr のコンセプト、セットアップ、設定、よくある問題の解決方法を教えるので、エージェントの回答が即興ではなく正確なままになります。
+
+## コアガイド
+
+<CardGrid>
+ <Card title="エージェント">
+ 対応エージェント、検出の挙動、インテグレーション、カスタムラベル、ダイレクトアタッチについて。
+
+ [エージェントを理解する →](/ja/docs/agents/)
+ </Card>
+ <Card title="セッション状態">
+ デタッチ、再起動時の復元、ペイン履歴のリプレイ、エージェントネイティブの resume、ライブハンドオフについて。
+
+ [状態管理の方式を比較する →](/ja/docs/session-state/)
+ </Card>
+ <Card title="設定">
+ キーバインド、テーマ、サイドバーの挙動、通知、スクロールバック、高度なオプションを設定します。
+
+ [Herdr を設定する →](/ja/docs/configuration/)
+ </Card>
+ <Card title="API">
+ CLI とローカルソケット API を通じて、スクリプト・ツール・エージェントから Herdr を制御します。
+
+ [API ガイドを読む →](/ja/docs/socket-api/)
+ </Card>
+ <Card title="プラグイン">
+ マニフェストのアクションとイベントフックを備えた、ローカル実行型ワークフロープラグインを作成します。
+
+ [プラグインを書く →](/ja/docs/plugins/)
+ </Card>
+ <Card title="マーケットプレイス">
+ 今すぐ GitHub からプラグインを共有し、リポジトリにトピックを付けてマーケットプレイス公開時に掲載されるようにしましょう。
+
+ [プラグインを公開する →](/ja/docs/marketplace/)
+ </Card>
+</CardGrid>
diff --git a/website/src/content/docs/ja/install.mdx b/website/src/content/docs/ja/install.mdx
new file mode 100644
index 00000000..d70b9f37
--- /dev/null
+++ b/website/src/content/docs/ja/install.mdx
@@ -0,0 +1,151 @@
+---
+title: Herdr のインストール
+description: Linux、macOS、Windows ベータでの Herdr のインストール、アップデート、動作確認。
+---
+
+Herdr は Linux と macOS 向けに安定版バイナリを提供しています。ネイティブ Windows 対応はプレビュー限定のベータです。
+
+## インストール
+
+Linux または macOS では次を実行します:
+
+```bash
+curl -fsSL https://herdr.dev/install.sh | sh
+```
+
+Windows プレビューベータでは、プレビューチャンネルをインストールします:
+
+```powershell
+powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
+```
+
+インストーラーはプラットフォームに合ったリリースバイナリをダウンロードして PATH 上に配置します。Windows インストーラーはデフォルトでプレビューを使い、そのチャンネルを Herdr の設定に書き込み、バージョン付きインストールフォルダーを使い、`current` ジャンクションを更新します。そのため、アップデート時に実行中の `herdr.exe` を上書きする必要がありません。
+
+## Homebrew でインストール
+
+すでに Homebrew を使っている場合:
+
+```bash
+brew install herdr
+```
+
+## mise でインストール
+
+すでに mise を使っている場合:
+
+```bash
+mise use -g herdr
+```
+
+mise が `herdr not found in mise tool registry` と報告する場合は、mise をアップデートして再試行してください。古い mise は Herdr のレジストリ登録より前のバージョンです。一時的な回避策として `mise use -g github:ogulcancelik/herdr` も使えます。
+
+## Nix でインストール
+
+すでに Nix を使っている場合、Herdr はソースからビルドする flake を提供しています:
+
+```bash
+nix run github:ogulcancelik/herdr/v0.x.y
+nix build github:ogulcancelik/herdr/v0.x.y
+nix profile install github:ogulcancelik/herdr/v0.x.y
+```
+
+`v0.x.y` は最新のリリースタグに置き換えてください。タグを省略すると `master` を追跡できますが、通常のインストールにはリリースタグを推奨します。
+
+flake は開発用シェルも公開しています:
+
+```bash
+nix develop github:ogulcancelik/herdr
+```
+
+アップデートは、Herdr のインストールに使ったのと同じ Nix ワークフローで行います。プロファイルインストールの場合は、プロファイルのエントリを一覧して Herdr のエントリをアップグレードします:
+
+```bash
+nix profile list
+nix profile upgrade <index-or-name>
+```
+
+Herdr が自分の flake の input になっている場合は、その input を更新してシステム、Home Manager、または開発環境を再ビルドします:
+
+```bash
+nix flake update herdr
+```
+
+## 手動でダウンロード
+
+[GitHub releases](https://github.com/ogulcancelik/herdr/releases) からバイナリをダウンロードすることもできます。
+
+システムに合ったアセットを選んでください:
+
+| システム | アセット |
+| --- | --- |
+| Linux x86_64 | `herdr-linux-x86_64` |
+| Linux aarch64 | `herdr-linux-aarch64` |
+| macOS Intel | `herdr-macos-x86_64` |
+| macOS Apple silicon | `herdr-macos-aarch64` |
+
+Linux または macOS では、実行可能にして PATH 上のどこかに移動します。
+
+```bash
+chmod +x herdr-linux-x86_64
+mv herdr-linux-x86_64 ~/.local/bin/herdr
+```
+
+### Windows ベータのダウンロード
+
+ネイティブ Windows 対応がベータの間、Windows バイナリはプレビューリリースでのみ公開されます。通常のテストには上記のプレビューインストーラーを使うか、プレビューの GitHub プレリリースから Windows アセットをダウンロードしてください:
+
+| システム | アセット |
+| --- | --- |
+| Windows x86_64 ベータ | `herdr-windows-x86_64.exe` |
+
+## 動作確認
+
+Herdr を起動します:
+
+```bash
+herdr
+```
+
+シェルが `herdr` を見つけられない場合は、ターミナルを再起動するか、インストール先ディレクトリが PATH に含まれているか確認してください。
+
+## アップデート
+
+Herdr は新しいリリースをチェックし、アプリ内で通知します。手動でアップデートすることもできます:
+
+```bash
+herdr update
+```
+
+`herdr update` は Herdr 自身のインストーラーで管理されているインストール向けです。Homebrew、mise、Nix のインストールは、それぞれのパッケージマネージャーでアップデートしてください。
+
+Linux と macOS では、Herdr はデフォルトで安定版アップデートチャンネルを使います。`master` からのプレビュービルドにオプトインするには、チャンネルを設定します:
+
+```bash
+herdr channel set preview
+```
+
+Linux と macOS の直接インストールを安定版に戻すのも同じ方法です:
+
+```bash
+herdr channel set stable
+```
+
+直接インストールの場合、チャンネルの変更はそのチャンネルをチェックして最新バイナリをインストールします。そのアップデートが失敗した場合は、`herdr update` を実行して設定済みチャンネルから再試行してください。
+
+プレビュービルドは、現在の開発ブランチから手動で公開される GitHub プレリリースです。次の安定版リリースより前に修正が欲しいときに便利ですが、リグレッションの可能性があります。Homebrew、mise、Nix のインストールはプレビューチャンネルを使いません。
+
+Windows ベータビルドは今のところプレビュー限定です。安定版の Windows リリースが提供されるまで、Windows では `herdr channel set stable` は拒否されます。
+
+デフォルトでは、`herdr update` は新しいバイナリをインストールし、互換性のある実行中セッションには手を付けません。アップデートが Herdr のクライアント/サーバープロトコルを変更する場合、Herdr はインストール後に古いサーバーを停止するか尋ねます。新しいバージョンを使うには古いサーバーを停止してください。停止するとペインのプロセスは終了します。デフォルトセッションでは `herdr server stop` を実行してから再度 `herdr` を実行します。名前付きセッションでは `herdr session stop <name>` を実行してから再度 `herdr session attach <name>` を実行します。
+
+対応する実行中セッションで実験的なライブサーバーハンドオフにオプトインするには:
+
+```bash
+herdr update --handoff
+```
+
+ライブハンドオフは Homebrew、mise、Nix のパッケージマネージャー経由のアップデートには適用されません。それらのインストールではパッケージマネージャーでアップデートし、新しいサーバーを使う準備ができたらその Herdr セッションを再起動してください。実行中のセッションがまだ古いサーバーを使っている場合は、`herdr server stop` または `herdr session stop <name>` で停止してから、再度 Herdr を実行します。
+
+## 動作要件
+
+Herdr の安定版リリースは Linux と macOS をサポートします。ネイティブ Windows ビルドはプレビュー限定のベータリリースです。サポートされるワークフローと既知の制限は [Windows ベータ](/ja/docs/windows-beta/)を参照してください。
diff --git a/website/src/content/docs/ja/integrations.mdx b/website/src/content/docs/ja/integrations.mdx
new file mode 100644
index 00000000..0930db49
--- /dev/null
+++ b/website/src/content/docs/ja/integrations.mdx
@@ -0,0 +1,286 @@
+---
+title: インテグレーション
+description: Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、Qoder CLI、Cursor Agent CLI 向けの Herdr インテグレーションをインストールします。
+---
+
+Herdr は対応エージェントを自動的に検出します。公式インテグレーションは、復元のためのネイティブセッション識別、ライフサイクル状態の報告、またはその両方を追加できます。
+
+Claude Code/Codex/Copilot/Devin 系のフックによるエージェントネイティブのセッション復元、Pi/OMP/Kimi/OpenCode/Kilo/Hermes 系のフックまたはプラグインによる直接のライフサイクル報告、あるいはその両方が欲しいときにインテグレーションを使ってください。状態権威モデルの全体像は[エージェント](/ja/docs/agents/)を参照してください。
+
+## インテグレーションをインストールする
+
+Herdr 内で設定を開き、インテグレーションタブから `PATH` 上で見つかったエージェント向けの推奨インテグレーションをインストールするか、コマンドを手動で実行します:
+
+```bash
+herdr integration install pi
+herdr integration install omp
+herdr integration install claude
+herdr integration install codex
+herdr integration install copilot
+herdr integration install devin
+herdr integration install droid
+herdr integration install kimi
+herdr integration install opencode
+herdr integration install kilo
+herdr integration install hermes
+herdr integration install qodercli
+herdr integration install cursor
+```
+
+## インテグレーションをアンインストールする
+
+```bash
+herdr integration uninstall pi
+herdr integration uninstall omp
+herdr integration uninstall claude
+herdr integration uninstall codex
+herdr integration uninstall copilot
+herdr integration uninstall devin
+herdr integration uninstall droid
+herdr integration uninstall kimi
+herdr integration uninstall opencode
+herdr integration uninstall kilo
+herdr integration uninstall hermes
+herdr integration uninstall qodercli
+herdr integration uninstall cursor
+```
+
+## Herdr がインテグレーションをどう使うか
+
+Herdr はインテグレーションを 2 つの異なる方法で使います:
+
+| インテグレーションの種類 | エージェント | 効果 |
+| --- | --- | --- |
+| ライフサイクル権威 | Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent | インストールされ、そのペインについて能動的に報告している間は、フックまたはプラグインのイベントが `idle`、`working`、`blocked` を決定します。同じライフサイクル権威に対して、Herdr はスクリーンマニフェストのフォールバックを併用しません。 |
+| セッション識別 | Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Qoder CLI、Cursor Agent CLI | インテグレーションは復元用のネイティブセッション参照を報告します。状態は引き続き Herdr のスクリーンマニフェスト検出から得られます。 |
+
+カスタムソケットインテグレーションも、ネイティブのターミナル UI では見えない状態を定義する場合に状態を報告できます。
+
+一部のインテグレーションは、エージェントのネイティブセッション参照を報告します。Herdr は公式のセッション参照を使って、`[session] resume_agents_on_restore = false` で無効化されていない限り、Herdr サーバーの再起動後に Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Cursor Agent CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode、Kilo Code CLI のペインを resume します。
+
+エージェントネイティブのセッション復元には最新の Herdr インテグレーションが必要です: Pi インテグレーションはバージョン `2`、OMP は `3`、Claude Code は `6`、Codex は `5`、GitHub Copilot CLI は `2`、Devin CLI は `2`、Droid は `2`、Kimi Code CLI は `3`、Qoder CLI は `2`、Cursor Agent CLI は `1`、OpenCode は `5`、Kilo Code CLI は `1`、Hermes Agent は `2` です。インストール済みバージョンは `herdr integration status` で確認してください。
+
+## Pi
+
+Pi インテグレーションをインストールします:
+
+```bash
+herdr integration install pi
+```
+
+Herdr はバンドルされた拡張を次の場所に書き込みます:
+
+```text
+~/.pi/agent/extensions/herdr-agent-state.ts
+```
+
+`PI_CODING_AGENT_DIR` が設定されている場合は、代わりに `$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts` に書き込みます。extensions ディレクトリはあらかじめ存在している必要があります。アンインストールはその拡張ファイルだけを削除します。
+
+## OMP
+
+OMP インテグレーションをインストールします:
+
+```bash
+herdr integration install omp
+```
+
+Herdr はバンドルされた拡張を次の場所に書き込みます:
+
+```text
+~/.omp/agent/extensions/herdr-omp-agent-state.ts
+```
+
+`PI_CODING_AGENT_DIR` が設定されている場合は、代わりに `$PI_CODING_AGENT_DIR/extensions/herdr-omp-agent-state.ts` に書き込みます。extensions ディレクトリはあらかじめ存在している必要があります。アンインストールはその拡張ファイルだけを削除します。
+
+OMP インテグレーションは、Herdr のソケット API を通じてエージェントラベル `omp`、ライフサイクル状態、ネイティブセッション識別を報告します。`omp` 実行ファイルのネイティブプロセス検出は不要で、Herdr はサーバー再起動後に `omp --resume=<session>` で OMP ペインを resume できます。
+
+## Claude Code
+
+Claude Code フックをインストールします:
+
+```bash
+herdr integration install claude
+```
+
+このフックは、セッション開始時に Claude Code のセッション識別をローカルの Herdr ソケットに報告します。Claude Code の状態は Herdr のスクリーンマニフェスト検出から得られます。
+
+Herdr はデフォルトで `~/.claude` を使い、`CLAUDE_CONFIG_DIR` が設定されていればそちらを使います。Claude の設定ディレクトリはあらかじめ存在している必要があります。インストールは `hooks/herdr-agent-state.sh` を書き込み、`settings.json` に Herdr のフックエントリを追加します。アンインストールは一致するフックエントリを削除し、フックスクリプトを削除します。
+
+## Codex
+
+Codex フックをインストールします:
+
+```bash
+herdr integration install codex
+```
+
+Codex フックは、他のインテグレーションと同じローカルソケット API を通じてセッション識別を報告します。Codex の状態は Herdr のスクリーンマニフェスト検出から得られます。
+
+Herdr はデフォルトで `~/.codex` を使い、`CODEX_HOME` が設定されていればそちらを使います。Codex の設定ディレクトリはあらかじめ存在している必要があります。インストールは `herdr-agent-state.sh` を書き込み、`hooks.json` を更新し、`config.toml` に `[features] hooks = true` があることを保証します。非推奨のトップレベル `codex_hooks` フラグが存在すれば削除もします。アンインストールは `hooks.json` から Herdr のエントリを削除してフックスクリプトを削除しますが、`config.toml` は変更しません。
+
+## GitHub Copilot CLI
+
+GitHub Copilot CLI フックをインストールします:
+
+```bash
+herdr integration install copilot
+```
+
+Copilot フックは、他のインテグレーションと同じローカルソケット API を通じてセッション識別を報告します。Copilot の状態は Herdr のスクリーンマニフェスト検出から得られます。
+
+Herdr はデフォルトで `~/.copilot` を使い、`COPILOT_HOME` が設定されていればそちらを使います。Copilot の設定ディレクトリはあらかじめ存在している必要があります。インストールは `hooks/herdr-agent-state.sh` を書き込み、`settings.json` に `SessionStart` フックエントリを追加します。アンインストールは `settings.json` から Herdr のエントリを削除し、フックスクリプトを削除します。
+
+Copilot がセッション情報を含むイベントを発行した後、Herdr は報告されたセッション id を使って `copilot --resume=<id>` でペインを resume できます。
+
+## Devin CLI
+
+Devin CLI フックをインストールします:
+
+```bash
+herdr integration install devin
+```
+
+このフックは、Devin のセッション、プロンプト、ツール使用、許可、停止の各イベントからネイティブセッション識別を報告します。Devin のフックはすべての許可キャンセルやユーザー割り込みの後に信頼できる状態遷移を発行しないため、Devin の状態は引き続き Herdr のスクリーンマニフェストと OSC 検出から得られます。
+
+Herdr はデフォルトで `~/.config/devin` を使い、`XDG_CONFIG_HOME` が設定されていれば `$XDG_CONFIG_HOME/devin` を使います。Devin の設定ディレクトリはあらかじめ存在している必要があります。インストールは `herdr-agent-state.sh` を書き込み、`config.json` に Herdr のフックエントリを追加します。フックは Devin の実行中にセッション参照を更新します。アンインストールは `config.json` から Herdr のエントリを削除し、フックスクリプトを削除します。
+
+Herdr は保存された Devin セッションを `devin --resume <id>` で resume します。フックのインストール有無にかかわらず、スクリーンマニフェスト検出が状態の権威のままです。
+
+## Kimi Code CLI
+
+Kimi Code CLI フックをインストールします:
+
+```bash
+herdr integration install kimi
+```
+
+このフックは、ネイティブ復元と権威ある `idle`、`working`、`blocked` 状態のために、Kimi のセッション識別とライフサイクル状態を Herdr に報告します。Kimi Code CLI `0.14.0` 以上が必要です。
+
+Herdr はデフォルトで `~/.kimi-code` を使い、`KIMI_CODE_HOME` が設定されていればそちらを使います。Kimi Code の設定ディレクトリはあらかじめ存在している必要があります。インストールは `hooks/herdr-agent-state.sh` を書き込み、`config.toml` に Herdr 管理の `[[hooks]]` エントリを追記します。アンインストールは Herdr 管理の設定ブロックを削除し、フックスクリプトを削除します。
+
+Herdr は保存された Kimi セッションを `kimi --session <id>` で resume します。
+
+## Droid
+
+Droid フックをインストールします:
+
+```bash
+herdr integration install droid
+```
+
+Droid フックは、他のインテグレーションと同じローカルソケット API を通じてセッション識別を報告します。Droid のフックはすべてのライフサイクル遷移をカバーしていないため、ライフサイクル状態は引き続き Herdr のスクリーンマニフェスト検出から得られます。
+
+Herdr は Droid フックに `~/.factory` を使います。Factory の設定ディレクトリはあらかじめ存在している必要があります。インストールは `hooks/herdr-agent-state.sh` を書き込み、`settings.json` に Herdr の `SessionStart` フックエントリを追加し、`hooks.json` に古い Herdr Droid フックエントリがあれば削除します。アンインストールは両方の設定ファイルから Herdr のエントリを削除し、フックスクリプトを削除します。
+
+Droid がセッション開始イベントを発行した後、Herdr は報告されたセッション id を使って `droid --resume <id>` でペインを resume できます。
+
+## OpenCode
+
+OpenCode プラグインをインストールします:
+
+```bash
+herdr integration install opencode
+```
+
+Herdr はプラグインを `~/.config/opencode/plugins/herdr-agent-state.js` に書き込みます。OpenCode の設定ディレクトリはあらかじめ存在している必要があります。アンインストールはそのプラグインファイルだけを削除します。
+
+このプラグインは、OpenCode が Herdr のペイン内で動いている間、ライフサイクル状態とセッション識別を報告します。OpenCode がセッション情報を含むイベントを発行した後、Herdr は報告されたセッション id を使って `opencode --session <id>` でペインを resume できます。プラグインがインストールされていないときは、スクリーンマニフェスト検出が引き続き利用できます。
+
+## Kilo Code CLI
+
+Kilo Code CLI プラグインをインストールします:
+
+```bash
+herdr integration install kilo
+```
+
+Herdr はプラグインを `~/.config/kilo/plugin/herdr-agent-state.js` に書き込みます。Kilo の設定ディレクトリはあらかじめ存在している必要があります。アンインストールはそのプラグインファイルだけを削除します。
+
+このプラグインは、Kilo が Herdr のペイン内で動いている間、ライフサイクル状態とセッション識別を報告します。Kilo がセッション情報を含むイベントを発行した後、Herdr は報告されたセッション id を使って `kilo --session <id>` でペインを resume できます。プラグインがインストールされていないときは、スクリーンマニフェスト検出が引き続き利用できます。
+
+## Hermes Agent
+
+Hermes Agent プラグインをインストールします:
+
+```bash
+herdr integration install hermes
+```
+
+Herdr は `~/.hermes/plugins/herdr-agent-state/` を書き込み、`~/.hermes/config.yaml` で `herdr-agent-state` を有効にします。Hermes の設定ディレクトリはあらかじめ存在している必要があります。プラグインを読み込ませるため、インストール後に Hermes を再起動してください。アンインストールはプラグインディレクトリを削除し、`plugins.enabled` から `herdr-agent-state` を削除します。
+
+このプラグインは、Hermes が Herdr のペイン内で動いている間、ライフサイクル、ツール、承認状態、セッション id を報告します。Herdr は報告されたセッション id を使って `hermes --resume <id>` でペインを resume できます。プラグインがインストールされていないときは、スクリーンマニフェスト検出が引き続き利用できます。
+
+## Qoder CLI
+
+Qoder CLI フックをインストールします:
+
+```bash
+herdr integration install qodercli
+```
+
+このフックは、ネイティブ復元のために Qoder CLI のセッション識別を Herdr に報告します。Qoder のフックはすべてのライフサイクル遷移をカバーしていないため、ライフサイクル状態は引き続き Herdr のスクリーンマニフェスト検出から得られます。
+
+Herdr はデフォルトで `~/.qoder` を使い、`QODER_CONFIG_DIR` が設定されていればそちらを使います。Qoder の設定ディレクトリはあらかじめ存在している必要があります。インストールは `hooks/herdr-agent-state.sh` を書き込み、`settings.json` に Herdr のフックエントリを追加します。アンインストールは一致するフックエントリを削除し、フックスクリプトを削除します。
+
+Herdr は保存された Qoder CLI セッションを `qodercli --resume <id>` で resume します。
+
+フックがインストールされていないときは、スクリーンマニフェスト検出が引き続き利用できます。
+
+## Cursor Agent CLI
+
+Cursor Agent CLI フックをインストールします:
+
+```bash
+herdr integration install cursor
+```
+
+このフックは、Cursor Agent CLI が Herdr のペイン内で動いている間、Cursor の `sessionStart` フックを通じてセッション識別を報告します。Cursor の状態は Herdr のスクリーンマニフェスト検出から得られます。
+
+Herdr はデフォルトで `~/.cursor` を使い、`CURSOR_CONFIG_DIR` が設定されていればそちらを使います。Cursor の設定ディレクトリはあらかじめ存在している必要があります。インストールは `herdr-agent-state.sh` を書き込み、`hooks.json` に Herdr の `sessionStart` エントリを追加します。アンインストールは一致するフックエントリを削除し、フックスクリプトを削除します。
+
+Cursor がセッション開始イベントを発行した後、Herdr は報告されたセッション id を使って `cursor-agent --resume <id>` でペインを resume できます。Herdr がペインを復元するとき、`cursor-agent` コマンドが `PATH` にある必要があります。Herdr は汎用の `agent` コマンドを起動しません。
+
+## カスタムステータスラベル
+
+インテグレーションは、意味的な状態を変えずに短い表示用ラベルを報告できます。
+
+たとえば、エージェントは意味的には `working` のまま、UI には `indexing` を表示できます。
+
+```bash
+herdr pane report-agent w1:p1 \
+ --source custom:docs \
+ --agent docs-bot \
+ --state working \
+ --custom-status indexing
+```
+
+Herdr 管理のインテグレーションと並走するユーザーフックは、`report-agent` ではなくメタデータを使うべきです。メタデータは、インテグレーションの `idle`、`working`、`blocked` やセッション復元の権威を奪わずに表示を変えます。`--agent` は、その権威あるエージェントがアクティブな間だけ報告が適用されるように保護します。`--applies-to-source` は、そのライフサイクル権威ソースがアクティブな間だけ報告が適用されるように保護します。`--display-agent` は表示名を変更します。
+
+```bash
+herdr pane report-metadata "$HERDR_PANE_ID" \
+ --source user:claude-title \
+ --agent claude \
+ --title "Refactor auth middleware" \
+ --display-agent "Claude: auth" \
+ --custom-status "refactor auth" \
+ --state-label working="refactoring auth" \
+ --ttl-ms 3600000
+```
+
+カスタムステータスと状態ラベルは表示専用です。wait、通知、ワークスペースのロールアップは引き続き意味的な状態を使います。
+
+## インテグレーション状態のデバッグ
+
+既知のエージェントを一覧します:
+
+```bash
+herdr agent list
+```
+
+Herdr に何が見えているか確認する必要があるときはペインを読みます:
+
+```bash
+herdr pane read w1:p1 --source recent --lines 50
+```
+
+インテグレーションの状態がおかしく見えるときは、まずエージェントが Herdr 内で動いていること、そして該当のフックまたはプラグインが同じユーザーアカウントにインストールされていることを確認してください。
diff --git a/website/src/content/docs/ja/keyboard.mdx b/website/src/content/docs/ja/keyboard.mdx
new file mode 100644
index 00000000..cb6a3f0d
--- /dev/null
+++ b/website/src/content/docs/ja/keyboard.mdx
@@ -0,0 +1,112 @@
+---
+title: キーボード
+description: プレフィックスとは何か、最初に覚えるべきバインド、プレフィックスなしで運用する方法。
+---
+
+:::tip[tmux や zellij から乗り換え?]
+このモデルはすでにご存じのはずです。完全なデフォルトキーマップと設定構文は[キーバインドリファレンス](/ja/docs/configuration/#キーバインド)へどうぞ。
+:::
+
+Herdr はマウスネイティブです。キーバインドをひとつも覚えなくても、ペイン、タブ、ワークスペース、エージェントをクリックし、分割境界をドラッグし、右クリックメニューを使えます。キーボード操作は任意のレイヤーであり、必須ではありません。
+
+## プレフィックスとは何か
+
+ターミナルマルチプレクサは、ターミナルとその中で動くプログラムの間に位置します。プログラムはすでにほとんどのキーの組み合わせを使っています: `ctrl+c` は中断、`ctrl+r` は履歴検索、エディタは残りのほぼすべてを占有します。もし Herdr がよく使われるキーを直接奪えば、中のプログラムを壊してしまいます。
+
+プレフィックスはこれを解決します。プレフィックスキー (デフォルト `ctrl+b`) を押すと、次のキー入力はターミナルではなく Herdr に送られます。`prefix+c` は「`ctrl+b` を押して離し、次に `c` を押す」という意味です。何十ものキーを予約する代わりに、ひとつだけ予約します。
+
+いつでも `prefix+?` を押すと、すべての有効なバインドが表示されます。
+
+## まずこの 5 つを覚える
+
+| アクション | キー |
+| --- | --- |
+| 新しいタブ | `prefix+c` |
+| 右 / 下に分割 | `prefix+v` / `prefix+minus` |
+| ペイン間の移動 | `prefix+h/j/k/l` |
+| ワークスペースナビゲーション | `prefix+w` |
+| すべてを動かしたままデタッチ | `prefix+q` |
+
+これで日常の移動のほとんどをカバーできます。それ以外はマウスのままで大丈夫です。
+
+## 残りはタスク別に
+
+ペイン:
+
+| アクション | キー |
+| --- | --- |
+| フォーカス中のペインをズーム | `prefix+z` |
+| ペインを閉じる | `prefix+x` |
+| ペインを入れ替える | `prefix+shift+h/j/k/l` |
+| リサイズモード | `prefix+r` |
+| コピーモード | `prefix+[` |
+
+タブ:
+
+| アクション | キー |
+| --- | --- |
+| 次 / 前のタブ | `prefix+n` / `prefix+p` |
+| タブ 1–9 にジャンプ | `prefix+1..9` |
+| タブの名前を変更 | `prefix+shift+t` |
+| タブを閉じる | `prefix+shift+x` |
+
+ワークスペースとセッション:
+
+| アクション | キー |
+| --- | --- |
+| 新しいワークスペース | `prefix+shift+n` |
+| ワークスペースの名前を変更 | `prefix+shift+w` |
+| ワークスペースを閉じる | `prefix+shift+d` |
+| Goto ピッカー | `prefix+g` |
+| サイドバーの表示切り替え | `prefix+b` |
+
+完全なキーマップとバインドの構文は[キーバインドリファレンス](/ja/docs/configuration/#キーバインド)にあります。
+
+## コピーモード
+
+`prefix+[` を押すと、フォーカス中のペインでコピーモードに入ります。`h/j/k/l`、`w/b/e`、`{`/`}` で移動し、`v` または Space で選択を開始し、`y` または Enter でコピーし、`q` または Esc でコピーせずに抜けます。マウスのドラッグ選択なら、コピーモードに入らずにそのままコピーできます。
+
+## 何でも変更できる
+
+プレフィックス自体を含め、すべてのバインドは設定可能です:
+
+```toml
+[keys]
+prefix = "ctrl+a"
+```
+
+## プレフィックスなしで運用する
+
+Herdr のアクションを、プレフィックス不要の直接コードに割り当てることもできます。難しいのはどのコードが安全かを知ることです。ターミナル、シェル、デスクトップ環境がすでにキーボードの大半を占有しているからです。
+
+どんなコードでもバインドにできます: `ctrl+j`、`alt+k`、手に馴染むものなら何でも。ただしコードが Herdr に届くまでには 3 つの層を通り抜ける必要があります: オペレーティングシステム、外側のターミナル (Ghostty、iTerm2 などは独自のデフォルトを持ちます)、そしてペイン内で動くプログラムです。`ctrl+j` は Herdr まで問題なく届きますが、シェルやエディタはそれを Enter として扱います。`alt+k` は Linux では空いていますが、macOS ではほとんどのターミナルで特殊文字に合成されます。これらの系統からコードを選ぶ場合は、自分のターミナルと OS のショートカットと衝突しないか確認してください。
+
+私たちは Ghostty、iTerm2、Terminal.app、kitty、WezTerm、Alacritty、Warp、Windows Terminal、GNOME Terminal、Konsole のデフォルトキーバインドと、GNOME および KDE のグローバルショートカットを調査しました。ほぼどこでも使われていない修飾キーの系統がひとつあります: `ctrl+alt` です。ターミナルはこれを空けたままにしており、素の `alt` コードを阻む macOS の option キー合成の影響も受けず、モダンなキーボードプロトコルのないターミナルでも送信されます。安全なデフォルトとしてお勧めしますが、選択はあなた次第です。
+
+この設定はプレフィックスバインドを維持したまま、直接コードを追加します:
+
+```toml
+[keys]
+focus_pane_left = ["prefix+h", "ctrl+alt+h"]
+focus_pane_down = ["prefix+j", "ctrl+alt+j"]
+focus_pane_up = ["prefix+k", "ctrl+alt+k"]
+focus_pane_right = ["prefix+l", "ctrl+alt+l"]
+previous_tab = ["prefix+p", "ctrl+alt+["]
+next_tab = ["prefix+n", "ctrl+alt+]"]
+new_tab = ["prefix+c", "ctrl+alt+c"]
+split_vertical = ["prefix+v", "ctrl+alt+d"]
+split_horizontal = ["prefix+minus", "ctrl+alt+shift+d"]
+zoom = ["prefix+z", "ctrl+alt+z"]
+```
+
+いくつかの `ctrl+alt` コードは他で使われています。これらは避けてください:
+
+| コード | 使用しているもの |
+| --- | --- |
+| `ctrl+alt+arrows` | GNOME のワークスペース切り替え、Ghostty と Konsole のデフォルト |
+| `ctrl+alt+t` | Ubuntu と Fedora の「ターミナルを起動」 |
+| `ctrl+alt+l` / `ctrl+alt+a` | KDE のロック画面 / アテンションウィンドウ |
+| `ctrl+alt+s` / `ctrl+alt+u` | Konsole |
+| `ctrl+alt+f1..f12` | Linux の仮想コンソール切り替え |
+
+直接コードを押しても何も起きない場合、Herdr に届く前にターミナルかデスクトップ環境がそれを消費しています。どちらかを再設定してください: ターミナルの設定でそのコードを解放するか、Herdr で別のコードを選びます。
diff --git a/website/src/content/docs/ja/marketplace.mdx b/website/src/content/docs/ja/marketplace.mdx
new file mode 100644
index 00000000..5f0a5c4c
--- /dev/null
+++ b/website/src/content/docs/ja/marketplace.mdx
@@ -0,0 +1,53 @@
+---
+title: マーケットプレイス
+description: GitHub 上のコミュニティ製 Herdr プラグインを探し、自分のプラグインを掲載する方法。
+---
+
+Herdr プラグインマーケットプレイスは、コミュニティ製プラグインを探せるインデックスです。
+[herdr.dev/plugins](/plugins/) で閲覧できます。これは公開 GitHub リポジトリの
+自動インデックスであり、審査済みカタログではありません。
+
+## プラグインを探す
+
+[マーケットプレイス](/plugins/)には、GitHub トピック `herdr-plugin` が付いた
+すべての公開リポジトリが掲載されます。名前、オーナー、説明、言語で検索でき、
+人気順、最近の活動順、新着順で並べ替えられます。各掲載はソースリポジトリの
+GitHub ページに直接リンクしています。
+
+掲載は自動かつ無審査です。掲載されているのはリポジトリが自らトピックを
+付けたからであって、Herdr が検証したからではありません。インストールする前に
+[信頼に関するガイダンス](/ja/docs/plugins/#信頼とセキュリティ)を確認してください。
+
+## プラグインをインストールする
+
+マーケットプレイスはインストールの上に発見の仕組みを足すものであり、
+インストールを置き換えるものではありません。どのプラグインも GitHub から
+直接インストールできます:
+
+```bash
+herdr plugin install owner/repo[/subdir...]
+```
+
+ルートまたはサブディレクトリに `herdr-plugin.toml` マニフェストを置いた
+通常の公開 GitHub リポジトリを公開すれば、このコマンドが機能します。
+マニフェストと作成方法のリファレンスは[プラグイン](/ja/docs/plugins/)を
+参照してください。
+
+## 自分のプラグインを掲載する
+
+公開リポジトリに GitHub トピック `herdr-plugin` を追加してください。
+インデックスが使うシグナルはこのトピックだけなので、公開プラグインに
+トピックを付けるだけで掲載されます。インデックスは 30 分ごとに自動更新される
+ため、新しくトピックを付けたリポジトリはまもなく表示され、トピックを外した
+リポジトリは次回の更新で消えます。
+
+## 掲載に表示される内容
+
+各カードには GitHub リポジトリのメタデータが表示されます: リポジトリ名と
+オーナー、説明、スター数、主要言語、最終 push 時刻、そしてソースへのリンクです。
+インデックスは GitHub のリポジトリ検索からこれらを読み取るため、リポジトリの
+説明とトピックを正確に保つことが、掲載を有用にする鍵になります。
+
+インデックスはまだ `herdr-plugin.toml` を解析しないため、プラグインの `id`、
+宣言された `platforms`、`min_herdr_version` といったマニフェストのフィールドは
+v1 では表示されません。フォークとアーカイブ済みリポジトリは一覧から除外されます。
diff --git a/website/src/content/docs/ja/persistence-remote.mdx b/website/src/content/docs/ja/persistence-remote.mdx
new file mode 100644
index 00000000..f8d3ff02
--- /dev/null
+++ b/website/src/content/docs/ja/persistence-remote.mdx
@@ -0,0 +1,132 @@
+---
+title: 永続化とリモートアクセス
+description: Herdr からのデタッチ、あとからの再アタッチ、名前付きセッション、SSH 越しの接続。
+---
+
+Herdr はペインをバックグラウンドサーバーで動かし続けます。ターミナルクライアントはデタッチして、あとで再接続できます。
+
+ローカル、SSH、`herdr --remote` の各ワークフローについては [Herdr での作業の進め方](/ja/docs/how-to-work/)を参照してください。
+
+## デタッチと再アタッチ
+
+`ctrl+b q` でクライアントをデタッチします。ペインとエージェントは動き続けます。再度 `herdr` を実行すると再アタッチします。セッションとそのペインを停止するには `herdr server stop` を使います。
+
+サーバーの完全停止後に Herdr が再起動すると、保存されたセッションの形を復元します。デタッチ、サーバー再起動、画面履歴リプレイ、エージェントネイティブのセッション復元、ライブハンドオフでそれぞれ何が生き残るかは[セッション状態と復元](/ja/docs/session-state/)を参照してください。
+
+## 名前付きセッション
+
+独立した Herdr サーバーが欲しいときは名前付きセッションを使います。
+
+```bash
+herdr session list
+herdr session attach work
+herdr session attach side-project
+herdr session stop work
+herdr session delete side-project
+```
+
+名前付きセッションは独自のペイン、タブ、ワークスペース、ソケット、ランタイム状態を持ちます。グローバル設定ファイルは共有されます。
+
+スクリプトでは `--json` を使ってください:
+
+```bash
+herdr session list --json
+herdr session stop work --json
+herdr session delete side-project --json
+```
+
+## SSH 越しのリモートアタッチ
+
+リモートモードは 2 つあり、[Herdr での作業の進め方](/ja/docs/how-to-work/)で比較しています。tmux スタイルの方法では、サーバーに SSH してそこで `herdr` を実行します。もうひとつは、ローカルマシンから SSH 越しにアタッチする方法です:
+
+```bash
+herdr --remote workbox
+herdr --remote ssh://you@server:2222
+```
+
+このモードでは、ローカルの Herdr はシンクライアントです。SSH 越しに接続し、リモートの Herdr サーバーを起動またはアタッチして、UI をローカルターミナルにストリーミングします。クライアントがローカルで動くため、Herdr は画像クリップボードの貼り付けのようなローカルデスクトップ機能をリモートセッションにブリッジできます。画像をリモートの一時ファイルにコピーし、そのパスを貼り付けます。
+
+デフォルトでは、`herdr --remote` はそのアタッチにローカルの Herdr キーバインドを使います。リモートサーバーの設定が異なっていても、ローカルの操作感覚を維持できます。ローカルキーバインドはアタッチ時のスナップショットなので、ローカルのキーバインドを編集したらデタッチして再アタッチしてください。リモートサーバーの設定を使いたい場合は `--remote-keybindings server` を使います。ローカルのカスタムコマンドキーバインドは送信されません。それらのコマンドはリモートホスト上で実行されてしまうからです。
+
+繰り返し接続する相手は SSH config を使ってください:
+
+```text
+Host workbox
+ HostName server.example.com
+ User you
+ Port 2222
+```
+
+その後はこれでアタッチできます:
+
+```bash
+herdr --remote workbox
+```
+
+リモートアタッチは x86_64 と aarch64 の Linux および macOS ホストをサポートします。Herdr はリモートのプラットフォームを確認し、リモートの `PATH` 上にある一致する `herdr` を優先し、次に `~/.local/bin/herdr` を確認します。一致するバイナリがない場合、対話的な実行では `~/.local/bin/herdr` へのインストールを提案します。非対話的な実行はホストを変更せずに失敗します。`~/.local/bin` がリモートの `PATH` にない場合、Herdr はインストール後に警告します。
+
+ネイティブ Windows の `herdr --remote` は Windows ベータの範囲外です。Windows からはサーバーに SSH してそこで `herdr` を実行してください。
+
+デフォルトでは、`herdr --remote` はあなたの SSH config を最初に include し、その後にフォールバックのキープアライブ設定を加えた一時的な SSH config を通してブリッジを実行します。既存のユーザーのキープアライブ設定が優先されます。Herdr が生成するブリッジ設定を使わず素の `ssh` を使うには `[remote].manage_ssh_config = false` を設定してください。
+
+デフォルトでは、実行中のリモートサーバーの置き換えや再起動が必要な場合、リモートアタッチは通常の再起動/停止フローを使います。対応する実行中リモートサーバーで実験的なライブハンドオフにオプトインするには `--handoff` を渡します:
+
+```bash
+herdr --remote workbox --handoff
+```
+
+先にサーバーへ SSH してそこで `herdr` を実行した場合、Herdr は完全にサーバー上で動きます。このモードは便利でシンプルですが、通常のターミナルテキスト貼り付けを超えてローカルデスクトップのクリップボードにはアクセスできません。
+
+ローカルとリモートのプラットフォームが一致する場合、直接インストールでは Herdr は現在のローカルバイナリをコピーできます。Homebrew、mise、Nix のインストールの場合、またはプラットフォームが異なる場合は、`https://herdr.dev/latest.json` から現在のクライアントバージョンに一致するリリースアセットをダウンロードします。
+
+ローカルビルドやカスタムバイナリの場合は、リモートアタッチの前に `HERDR_REMOTE_BINARY` にローカルファイルパスを設定してください。
+
+```bash
+HERDR_REMOTE_BINARY=target/release/herdr herdr --remote workbox
+```
+
+## リモートの名前付きセッション
+
+リモートホスト上の名前付きセッションにアタッチするには、`--remote` と一緒に `--session` を使います:
+
+```bash
+herdr --remote workbox --session agents
+```
+
+## ダイレクトターミナルアタッチ
+
+完全な Herdr アタッチはワークスペース UI 全体を開きます。ダイレクトアタッチは、サーバーが所有するターミナルをひとつだけ、現在のターミナルに開きます。
+
+ダイレクトターミナルアタッチは Windows ベータでは Unix 専用です。
+
+エージェントターゲットでアタッチ:
+
+```bash
+herdr agent attach reviewer
+```
+
+ターミナル ID でアタッチ:
+
+```bash
+herdr terminal attach term_abc123
+```
+
+ダイレクトアタッチは、現在レンダリングされているターミナル状態をストリーミングし、その後ライブの ANSI フレームを流します。入力はそのターミナルに直接送られます。
+
+`ctrl+b q` でデタッチします。リテラルの `ctrl+b` は `ctrl+b ctrl+b` で送ります。
+
+ひとつのターミナルの入力とリサイズを所有できる書き込み可能なダイレクトアタッチクライアントはひとつだけです。既存の所有者を置き換えるには `--takeover` を使います:
+
+```bash
+herdr terminal attach term_abc123 --takeover
+```
+
+## シングルプロセスの逃げ道
+
+バックグラウンドのサーバー/クライアント分離なしで Herdr を実行するには `--no-session` を使います:
+
+```bash
+herdr --no-session
+```
+
+これは主にデバッグや互換性のための逃げ道です。デフォルトの永続セッションモードが通常の使い方です。
diff --git a/website/src/content/docs/ja/plugins.mdx b/website/src/content/docs/ja/plugins.mdx
new file mode 100644
index 00000000..ab9bfec4
--- /dev/null
+++ b/website/src/content/docs/ja/plugins.mdx
@@ -0,0 +1,318 @@
+---
+title: プラグイン
+description: マニフェストのアクション、イベントフック、ペインを備えたローカル Herdr プラグインを作成します。
+---
+
+Herdr プラグインは、共有可能で実行可能なワークフローパッケージです。プラグインは
+Bash スクリプト、JavaScript アプリ、Lua スクリプト、Rust バイナリ、その他マシンで
+実行できる任意の argv コマンドにできます。Herdr はホスト側の面を担います:
+インストール、マニフェスト検証、キーバインド、ターミナルペイン、イベント、
+呼び出しコンテキスト、ソケットアクセスです。プラグインは自分の実装言語、依存関係、
+ファイル、永続状態を担います。
+
+プラグインは Herdr を軽量に保つために存在します。コアはターミナルワークスペース、
+ペイン、エージェント、安定した CLI/ソケット API に集中し続けます。プラグインは
+その既存の拡張面を、あらゆるワークフローを Herdr 本体に追加することなく、
+誰もが作成・インストール・共有できる再利用可能なワークフローに変えます。
+
+プラグインは SDK インテグレーションではありません。`herdr-plugin.toml`
+マニフェストと、Herdr が起動できるコマンドを持つディレクトリです。Herdr は
+マニフェストを検証し、ランタイムコンテキストを注入し、宣言されたコマンドを起動し、
+ログを記録します。コマンドはさらに作業が必要なときに、CLI またはソケット経由で
+Herdr を呼び出します。
+
+独立したプラグイン SDK や制限付きコマンドセットはありません。Herdr CLI 全体が
+プラグイン API です: [CLI リファレンス](/ja/docs/cli-reference/)のすべてのコマンドを
+プラグインから使えます。自分で `herdr ...` として実行できるものは、プラグインも
+実行できます。ほとんどのプラグインは、実行中の Herdr バイナリを指す
+`HERDR_BIN_PATH` を通じて Herdr を呼び出すべきです。これにより、Unix ソケットと
+Windows 名前付きパイプの両方でプラグインの移植性が保たれます。生の JSON リクエストを
+自分で送りたいときは[ソケット API](/ja/docs/socket-api/)を使ってください。
+
+ランタイムでのアクション登録と、ターミナル以外のネイティブなプラグイン UI は
+プラグイン v1 の範囲外です。アクション、イベントフック、ペイン、リンクハンドラーは
+すべてマニフェストで宣言します。
+
+## 信頼とセキュリティ
+
+プラグインはあなたのマシンで動く普通のコードです。インストールまたはリンクすると、
+そのビルドコマンドとランタイムコマンドはあなたのユーザーとして、あなたの環境で
+実行され、Herdr CLI 全体を呼び出せます — エディタ、シェル、コーディングエージェントに
+追加する拡張機能と同じです。この開放性こそが狙いであり、少しの判断力があれば
+安全に保てます。
+
+信頼できる作者とリポジトリからプラグインをインストールし、新しいプラグインが
+何をするのか先に目を通してください: `herdr-plugin.toml` マニフェストと、実行される
+スクリプトやバイナリです。`herdr plugin install` は対話的なターミナルでソースと
+実行されるコマンドのプレビューを表示するので、確定する前に確認できます。すでに
+信頼しているソースには `--yes` を使い、特定のリビジョンが欲しいときは `--ref` で
+固定してください。
+
+Herdr はマニフェストを検証し、各プラグインの設定と状態を専用ディレクトリに
+保ちますが、プラグインの動作をレビューしたりサンドボックス化したりはしません。
+サードパーティのプラグインは Herdr ではなく作者のものです。検証と実行の判断は
+あなた自身に委ねられます。
+
+## マニフェスト
+
+マニフェストは Herdr とプラグインの間の契約です。パッケージのメタデータ、対応
+プラットフォーム、任意のビルドコマンド、Herdr が実行できるエントリーポイントを
+宣言します。
+
+```toml
+id = "example.layout"
+name = "Layout"
+version = "0.1.0"
+min_herdr_version = "0.7.0"
+description = "Apply project layouts"
+platforms = ["linux", "macos", "windows"]
+
+[[build]]
+command = ["npm", "ci"]
+
+[[build]]
+command = ["npm", "run", "build"]
+platforms = ["linux", "macos"]
+
+[[actions]]
+id = "apply"
+title = "Apply layout"
+contexts = ["workspace"]
+command = ["node", "dist/apply.js"]
+
+[[events]]
+on = "worktree.created"
+command = ["herdr", "workspace", "list"]
+
+[[panes]]
+id = "board"
+title = "Project board"
+placement = "overlay"
+command = ["herdr-board"]
+
+[[link_handlers]]
+id = "github-issue"
+title = "Open GitHub issue"
+pattern = "^https://github\\.com/[^/]+/[^/]+/(issues|pull)/[0-9]+$"
+action = "apply"
+```
+
+トップレベルの `id`、`name`、`version`、`min_herdr_version` は必須です。
+`min_herdr_version` には、プラグインが使うプラグイン API、イベント名、
+マニフェストフィールドをサポートする最も古い Herdr バージョンを設定してください。
+プラグインの最低バージョンが現在のバイナリより新しい場合、Herdr はリンクや
+インストールを拒否します。`description` は任意です。プラグイン id には ASCII の
+英字、数字、ドット、コロン、アンダースコア、ハイフンが使えます。
+
+アクション id、ペイン id、リンクハンドラー id はプラグイン内部のローカル id です。
+ASCII の英字、数字、コロン、アンダースコア、ハイフンが使えますが、ドットは
+使えません。各 id の種類はプラグイン内で一意でなければなりません。グローバルに
+一意な名前が必要なとき、Herdr はアクション id を `plugin.id.action` の形に修飾します。
+
+プラグインが動作する場所は `platforms = ["linux", "macos", "windows"]` で宣言します。
+ビルドコマンド、アクション、イベントフック、ペイン、リンクハンドラーも独自の
+`platforms` を宣言でき、項目レベルの platforms はトップレベルのリストを
+上書きします。トップレベルの `platforms` がないローカルプラグインは警告付きで
+リンクされます。
+
+`command` の値は argv 配列です。Herdr はこれをシェル経由で実行しないため、
+コマンド自身がシェルを起動しない限りシェル展開はありません。言語固有の挙動は
+スクリプトやバイナリの側に置いてください。
+
+## 最初のプラグイン
+
+`herdr-plugin.toml` と実行可能なスクリプトまたはプログラムをひとつ含む
+ディレクトリから始めます:
+
+```text
+my-plugin/
+ herdr-plugin.toml
+ index.js
+```
+
+```toml
+id = "example.workspace-tools"
+name = "Workspace Tools"
+version = "0.1.0"
+min_herdr_version = "0.7.0"
+description = "Small workspace helpers"
+platforms = ["linux", "macos", "windows"]
+
+[[actions]]
+id = "list-workspaces"
+title = "List workspaces"
+contexts = ["workspace"]
+command = ["node", "index.js"]
+```
+
+コマンドの中からは `HERDR_BIN_PATH` で Herdr を呼び出します:
+
+```js
+const { spawnSync } = require("node:child_process");
+
+const herdr = process.env.HERDR_BIN_PATH ?? "herdr";
+const result = spawnSync(herdr, ["workspace", "list"], {
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "pipe"],
+});
+
+process.stdout.write(result.stdout);
+process.stderr.write(result.stderr);
+process.exit(result.status ?? 1);
+```
+
+この例は Node を使っていますが、プラグインに Node は必須ではありません。
+マニフェストは Bash、PowerShell、Python、Rust、Go、Lua、Bun など、ユーザーの
+マシンで使える任意のコマンドを起動できます。
+
+## インストールとリンク
+
+サンプルプラグインをインストールします:
+
+```bash
+herdr plugin install ogulcancelik/herdr-plugin-examples/agent-telegram-notify
+herdr plugin config-dir examples.agent-telegram-notify
+herdr plugin list
+herdr plugin action list --plugin examples.agent-telegram-notify
+```
+
+ローカルでプラグインを作成しているときは、代わりに作業ディレクトリをリンクします:
+
+```bash
+herdr plugin link /path/to/plugin
+herdr plugin config-dir example.layout
+herdr plugin action list --plugin example.layout
+herdr plugin action invoke example.layout.apply
+herdr plugin pane open --plugin example.layout --entrypoint board
+herdr plugin log list --plugin example.layout
+```
+
+`plugin install` は `owner/repo/subdir` のような GitHub 省略記法のみを受け付けます。
+`git` でクローンし、対話的なターミナルではプレビューを表示し、サポートされる
+ビルドコマンドを実行し、チェックアウトを Herdr 管理のプラグインデータの下に保存して
+登録します。非対話的なインストールには `--yes` を使ってください。GitHub 管理の
+プラグインを再インストールすると、その管理チェックアウトが置き換えられます。
+ローカルにリンクされたプラグインへの上書きインストールは拒否されます。先に
+ローカルプラグインを unlink または uninstall してください。`plugin install` と
+`plugin link` はプラグインの設定・状態ディレクトリを作成し、
+`plugin config-dir <id>` はセットアップドキュメントやシェルスクリプト向けに
+設定ディレクトリを表示します。
+
+`plugin uninstall <id-or-source>` はプラグインの登録を解除します。GitHub 管理の
+インストールでは管理チェックアウトも削除し、プラグイン id と、install で使うのと
+同じ `owner/repo[/subdir...]` 省略記法の両方を受け付けます。`plugin unlink <id>` は
+登録解除のみを行いファイルには触れないため、ローカル開発に便利です。v1 に独立した
+`plugin update` はありません。管理プラグインを更新するには GitHub から
+再インストールしてください。
+
+サンプル集のリポジトリは `ogulcancelik/herdr-plugin-examples` です。
+`agent-telegram-notify`、`github-link-preview`、`dev-layout-bootstrap` を含む
+独立したサンプルプラグインがサブディレクトリに入っています。これらはコピーする
+ためのサンプルであり、メンテナンスされる公式プラグインではありません。
+
+## ビルドコマンド
+
+ビルドコマンドは GitHub からの `plugin install` 中、確認の後、Herdr がプラグインを
+登録する前に実行されます。ビルドコマンドが失敗するとインストールは中止され、
+プラグインは登録されません。`plugin link` はビルドコマンドを実行しません。
+ローカルの作者は自分で作業ツリーをビルドします。ビルドコマンドはファイルを生成して
+構いませんが、インストールプレビュー後に `herdr-plugin.toml` を変更すると
+インストールは中止されます。ビルド失敗時には、プラグイン id、ビルドのインデックス、
+作業ディレクトリ、コマンド、終了ステータスまたは spawn エラー、上限付きの
+stdout/stderr が、ツールの出力を解釈せずに表示されます。
+
+ビルドコマンドも素の argv コマンドですが、ランタイムのプラグインコンテキストや
+Herdr のソケット環境変数は受け取りません。プラグインの作者は `cargo`、`npm`、
+`bun`、`lua` といった必要なシステムツールをドキュメントに書いてください。Herdr は
+ビルドの失敗を報告しますが、足りないツールチェーンをインストールすることはありません。
+
+## コマンドと環境
+
+ランタイムコマンドは、プラグインディレクトリを作業ディレクトリとして実行されます。
+Herdr は `HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ENV=1`、
+`HERDR_PLUGIN_ID`、`HERDR_PLUGIN_ROOT`、`HERDR_PLUGIN_CONFIG_DIR`、
+`HERDR_PLUGIN_STATE_DIR`、`HERDR_PLUGIN_CONTEXT_JSON`、そして利用可能なら
+`HERDR_WORKSPACE_ID`、`HERDR_TAB_ID`、`HERDR_PANE_ID` を注入します。アクション
+コマンドは加えて `HERDR_PLUGIN_ACTION_ID` を受け取ります。イベントフックは
+`HERDR_PLUGIN_EVENT` と `HERDR_PLUGIN_EVENT_JSON` を、ペインコマンドは
+`HERDR_PLUGIN_ENTRYPOINT_ID` を受け取ります。
+
+`HERDR_PLUGIN_ROOT` は、インストールまたはリンクされたプラグインディレクトリです。
+GitHub からインストールされたプラグインのルートは管理されたソースチェックアウト
+なので、そこにユーザーの認証情報や永続状態を保存しないでください。`.env` ファイルの
+ようなユーザーが編集する設定は `HERDR_PLUGIN_CONFIG_DIR` の下に、ローカルの
+ランタイム状態は `HERDR_PLUGIN_STATE_DIR` の下に置いてください。Herdr はこれらの
+ディレクトリを作成し、レガシーなプラグイン設定の場所が存在すれば
+`HERDR_PLUGIN_CONFIG_DIR` に初期内容を移しますが、その中身の検証、同期、削除は
+しません。ファイル形式とライフサイクルはプラグインが所有します。
+
+`HERDR_PLUGIN_CONTEXT_JSON` には、その呼び出しで利用可能な場合、ワークスペース、
+タブ、フォーカス中のペイン、worktree、エージェント、選択テキスト、クリックされた
+URL、リンクハンドラーのフィールドが含まれます。シェルプラグインは、よく使う id は
+個別の環境変数から読み、完全な形が必要ならコンテキスト JSON をパースできます。
+
+Node、PowerShell、Bash など別のランタイムから移植性を保って Herdr を呼び出す必要が
+あるときは `HERDR_BIN_PATH` を使ってください。`HERDR_SOCKET_PATH` の背後にある生の
+ソケットトランスポートは OS 固有です: Unix クライアントは Unix ソケットパスに、
+Windows クライアントは名前付きパイプに接続します。`HERDR_BIN_PATH` を通じた CLI
+呼び出しなら、そのトランスポートの違いを気にせずに済みます。利用可能なコマンドは
+[CLI リファレンス](/ja/docs/cli-reference/)、生のリクエスト形式は
+[ソケット API](/ja/docs/socket-api/)を参照してください。
+
+## ペイン
+
+マニフェストのペイン `placement` のデフォルトは `overlay` で、アクティブなペインの
+上に一時的なズームオーバーレイを開き、閉じるときに以前のフォーカスとズームを
+復元します。`plugin.pane.open` リクエストは、マニフェストの placement を
+`overlay`、`split`、`tab`、`zoomed` で上書きできます。
+
+プラグインペインは、開いた後は通常の Herdr ペインです。プラグインはソケットや CLI を
+通じて `pane.move`、`pane.swap`、`pane.resize`、`pane.zoom` といった標準のペイン
+API を呼び出せます。ペインがタブやワークスペースをまたいで移動しても、Herdr は
+プラグインペインの所有権を元のペインに結び付けたまま維持します。
+
+Windows では、ビルドコマンド、アクションコマンド、イベントコマンドは、素の
+コマンドが `PATH` にあれば `npm.cmd`、`bun.cmd`、`pnpm.cmd` のような一般的な
+`PATHEXT` shim を解決します。ペインコマンドは Herdr の通常の Windows ペイン
+ランチャーを使うため、引き続き有効な Windows の argv コマンドでなければなりません。
+
+## キーバインド
+
+インストール済みプラグインのアクションにキーを割り当てます:
+
+```toml
+[[keys.command]]
+key = "prefix+l"
+type = "plugin_action"
+command = "example.layout.apply"
+description = "apply layout"
+```
+
+## リンクハンドラー
+
+`[[link_handlers]]` を使うと、マッチしたターミナル URL への修飾キー付きクリックを、
+ブラウザで URL を開く代わりにプラグインのアクションにルーティングできます。
+修飾キー付きクリックの修飾キーは macOS を含むすべてのプラットフォームで Control
+です。キャプチャされたターミナルのマウスレポートは、Command/Super を通常のクリックと
+区別して伝えないからです。`pattern` はクリックされた URL に対してマッチする Rust の
+正規表現で、`action` には同じプラグインが宣言したアクション名を指定します。リンク
+ハンドラーのアクションは `HERDR_PLUGIN_CONTEXT_JSON` で
+`invocation_source = "link_click"`、`clicked_url`、`link_handler_id` を受け取ります。
+シェルプラグインは `HERDR_PLUGIN_CLICKED_URL` と `HERDR_PLUGIN_LINK_HANDLER_ID` も
+読めます。ハンドラーは各プラグイン内でマニフェストの順にチェックされます。
+
+## ストレージ
+
+v1 には Herdr が管理するプラグインストレージ API はありません。永続状態が必要な
+プラグインは、自分のファイルやデータベースを持ってください。
+
+## マーケットプレイス
+
+コミュニティ製プラグインは[マーケットプレイス](/plugins/)で探せます。これは
+GitHub トピック `herdr-plugin` が付いた公開 GitHub リポジトリの自動インデックスです。
+プラグインは普通の GitHub リポジトリのままです: `herdr-plugin.toml` を含めて公開し、
+`herdr plugin install owner/repo[/subdir]` を共有してください。
+
+プラグインを掲載するには、公開リポジトリに GitHub トピック `herdr-plugin` を
+追加します。インデックスは 30 分ごとに更新されます。発見の仕組みは
+[マーケットプレイス](/ja/docs/marketplace/)を参照してください。
diff --git a/website/src/content/docs/ja/quick-start.mdx b/website/src/content/docs/ja/quick-start.mdx
new file mode 100644
index 00000000..4de15f61
--- /dev/null
+++ b/website/src/content/docs/ja/quick-start.mdx
@@ -0,0 +1,69 @@
+---
+title: クイックスタート
+description: 最初の Herdr ワークスペースを作成し、永続的なターミナルペインでエージェントを動かします。
+---
+
+Herdr をまだインストールしていない場合は[インストール](/ja/docs/install/)を参照してください。その後、任意のプロジェクトディレクトリから Herdr を起動します:
+
+```bash
+herdr
+```
+
+Herdr はデフォルトのバックグラウンドセッションを起動するか、それにアタッチします。ソケットを管理する必要はありません。デタッチしてもエージェントは動き続けます。
+
+## ワークスペースを作成する
+
+セッションにワークスペースがない場合、Herdr は自動的にひとつ開きます。ワークスペースはタブ、ペイン、エージェントを入れるプロジェクト単位のコンテナです。アクティブなプロジェクトごとに専用のワークスペースを作ってください。そうすることでサイドバーのエージェント状態が読みやすくなります。
+
+## マウスを使う
+
+Herdr はマウスネイティブなので、まずはクリックから始めてください。ペイン、タブ、ワークスペース、エージェントをクリックしてフォーカスします。分割境界をドラッグしてリサイズします。右クリックでコンテキストメニューが開き、ペインの分割やタブの作成ができます。テキストをドラッグ選択するとクリップボードにコピーされます。トークンをダブルクリックすると直接コピーされます。コピーに Ctrl+C は不要です。
+
+ターミナルが修飾キー付きクリックを Herdr に渡す場合、Ctrl+クリックでペイン内のリンクを開けます。これは OSC 8 ハイパーリンクと、表示されている `http://` または `https://` の URL で機能します。macOS では、マウスキャプチャが有効な間は Herdr が処理するペインリンクに Ctrl+クリックを使ってください。Cmd+クリックは Shift+Cmd+クリックや `ui.mouse_capture = false` といったターミナルネイティブのバイパス経路でのみ使えます。
+
+`ui.right_click_passthrough_modifier` を設定すると、その修飾キー + 右クリックで、右クリック・ホールド・ドラッグのジェスチャーがマウスレポーティング対応のペインアプリに送られます。
+
+## エージェントを動かす
+
+ペインの中でコーディングエージェントを起動します:
+
+```bash
+claude
+```
+
+`codex`、`pi`、`opencode` など、他の[対応エージェント](/ja/docs/agents/)でも構いません。Herdr は自動的に検出します。サイドバーには各エージェントが `working`、`blocked`、`done`、`idle` のどれかが表示されます — すべてのワークスペースを横断して表示されるので、どのプロジェクトがあなたを必要としているか常に分かります。
+
+## キーボード操作
+
+キーボード操作は任意です。マウスですべての操作ができます。`ctrl+b` を押してプレフィックスモードに入り、アクションキーを押します。
+
+よく使うアクション:
+
+| アクション | キー |
+| --- | --- |
+| 右に分割 | `prefix+v` |
+| 下に分割 | `prefix+minus` |
+| 新しいタブ | `prefix+c` |
+| 次 / 前のタブ | `prefix+n` / `prefix+p` |
+| ワークスペースナビゲーション | `prefix+w` |
+| 新しいワークスペース | `prefix+shift+n` |
+| クライアントをデタッチ | `prefix+q` |
+
+プレフィックスの考え方が初めてなら、[キーボード](/ja/docs/keyboard/)でプレフィックスとは何か、なぜマルチプレクサがこれを使うのか、プレフィックスなしで運用する方法を説明しています。Herdr 内で `prefix+?` を押すとすべての有効なバインドが表示され、`prefix+[` でコピーモードに入ってキーボードからコピーできます。
+
+## デタッチして戻ってくる
+
+`prefix+q` を押すか、単純にターミナルウィンドウを閉じてください。Herdr サーバーとすべてのエージェントは動き続けます。もう一度 `herdr` を実行すると同じセッションに再アタッチします。
+
+セッションを本当に終了してペインを停止するには:
+
+```bash
+herdr server stop
+```
+
+## 次に読むもの
+
+- [コンセプト](/ja/docs/concepts/) — ワークスペース、タブ、ペイン、エージェントのモデルを 2 分で。
+- [Herdr での作業の進め方](/ja/docs/how-to-work/) — ローカル、SSH、スマートフォン、`herdr --remote` のワークフロー。
+- [エージェント](/ja/docs/agents/) — 対応エージェント、検出、状態の精度を高めるインテグレーション。
+- [設定](/ja/docs/configuration/) — キーバインド、テーマ、通知、その他すべて。
diff --git a/website/src/content/docs/ja/session-state.mdx b/website/src/content/docs/ja/session-state.mdx
new file mode 100644
index 00000000..95bc0d28
--- /dev/null
+++ b/website/src/content/docs/ja/session-state.mdx
@@ -0,0 +1,104 @@
+---
+title: セッション状態と復元
+description: Herdr が何をライブで維持し、再起動後に何を復元し、履歴から何をリプレイし、エージェントインテグレーションで何を resume し、アップデート時に何をハンドオフするかを理解します。
+---
+
+Herdr には複数の状態管理経路があります。それぞれが異なる問題を解決します。
+
+## 何が生き残るか
+
+| ケース | プロセスは動き続ける | レイアウトは戻る | 直近の画面は戻る | エージェントの会話は再開する |
+| --- | --- | --- | --- | --- |
+| デタッチと再アタッチ | はい | はい | はい (ライブのターミナルから) | はい (プロセスが止まらないため) |
+| サーバー再起動 | いいえ | はい | ペイン画面履歴が有効な場合のみ | エージェントネイティブのセッション復元がある場合のみ |
+| `--handoff` なしのアップデート | 互換性のあるサーバーは動き続ける。再起動が必要なサーバーは停止/再起動が必要な場合がある | 再起動後は戻る | ペイン画面履歴が有効な場合のみ | エージェントネイティブのセッション復元がある場合のみ |
+| `--handoff` ありのアップデート | 対応する稼働中サーバーではベストエフォート | はい | はい (ハンドオフが成功すればライブのターミナルから) | はい (ハンドオフが成功すればプロセスが動き続けるため) |
+
+以下のセクションでそれぞれの経路を説明します。
+
+## ライブ永続化
+
+通常のデタッチでは Herdr サーバーは動き続けます。ペイン、シェル、エージェント、サーバー、テスト、コマンドプロセスはそのサーバー内で動き続けます。
+
+`ctrl+b q` でクライアントをデタッチします。あとで再アタッチします:
+
+```bash
+herdr
+```
+
+元のプロセスが一度も止まらないため、これが最も強力な永続化経路です。
+
+## スナップショット復元
+
+Herdr サーバーが停止して再起動すると、元のペインのプロセスは失われています。Herdr は保存されたセッションの形を復元します: ワークスペース、タブ、ペイン、cwd、レイアウト、フォーカスです。
+
+スナップショット復元は、動作中のシェル、サーバー、テスト、その他任意のプロセスを保存しません。より強力な復元経路が使えないペインは、保存されたディレクトリで新しいシェルとして戻ってきます。
+
+## ペイン画面履歴のリプレイ
+
+ペイン画面履歴は、サーバーの完全な再起動後に直近のターミナル内容を復元します。復元されるのは Herdr が表示できるものであって、元のプロセスではありません。
+
+ペイン出力にはシークレット、トークン、プロンプト、コマンド出力が含まれうるため、これはデフォルトで無効です。Settings > Experiments > pane screen history から、または次の設定で有効にします:
+
+```toml
+[experimental]
+pane_history = true
+```
+
+有効にすると、Herdr は保存したペイン履歴を `session.json` の隣の `session-history.json` に保存します。Herdr の設定/セッションディレクトリはターミナル履歴と同じ感覚で扱ってください。
+
+## エージェントネイティブのセッション復元
+
+一部のエージェントは自分の会話セッションを resume できます。Herdr は、公式インテグレーションが報告したセッション参照を使って、Herdr サーバーの再起動後に対応エージェントのペインを再起動できます。
+
+これはデフォルトで有効です。無効にするには:
+
+```toml
+[session]
+resume_agents_on_restore = false
+```
+
+Herdr が resume するのは、現行の公式 Herdr インテグレーションを通じてネイティブセッション参照を報告したペインだけです。
+
+クライアントがアタッチしてターミナルサイズとテーマのコンテキストを提供すると、Herdr は各ペインがフォーカスされるのを待たずに、ワークスペースとタブをまたいで復元対象のエージェントペインを resume します。
+
+エージェントネイティブのセッション復元には、次の Herdr インテグレーションバージョン以上が必要です:
+
+| エージェント | 最低 Herdr インテグレーションバージョン | resume コマンド |
+| --- | --- | --- |
+| Pi | `2` | `pi --session <path-or-id>` |
+| OMP | `3` | `omp --resume=<path-or-id>` |
+| Claude Code | `6` | `claude --resume <id>` |
+| Codex | `5` | `codex resume <id>` |
+| Cursor Agent CLI | `1` | `cursor-agent --resume <id>` |
+| GitHub Copilot CLI | `2` | `copilot --resume=<id>` |
+| Devin CLI | `2` | `devin --resume <id>` |
+| Droid | `2` | `droid --resume <id>` |
+| Kimi Code CLI | `3` | `kimi --session <id>` |
+| Qoder CLI | `2` | `qodercli --resume <id>` |
+| OpenCode | `5` | `opencode --session <id>` |
+| Kilo Code CLI | `1` | `kilo --session <id>` |
+| Hermes Agent | `2` | `hermes --resume <id>` |
+
+インストール済みインテグレーションのバージョンは `herdr integration status` で確認できます。古いインテグレーションは `herdr integration install <agent>` で再インストールしてください。
+
+未対応、欠落、無効、重複、または古くなったセッション参照は、保存されたペインディレクトリで通常のシェルとして復元されます。
+
+あるペインにエージェントネイティブのセッション復元が適用される場合、Herdr はそのペインでは保存済みペイン履歴のリプレイではなくエージェントセッションの resume を行います。
+
+## ライブハンドオフ
+
+ライブハンドオフは、稼働中の Herdr サーバーを置き換える必要があるアップデートやリモートアタッチのフローのためのものです。古いサーバーにライブペインを新しいサーバーへ移すよう依頼し、サーバー交換をまたいでペインのプロセスが動き続けられるようにします。
+
+これはスナップショット復元、ペイン履歴リプレイ、エージェントネイティブのセッション復元とは異なります。ハンドオフは現在のプロセスを生かし続けようとします。他の経路は、古いサーバーが停止した後に状態を再構築します。
+
+ライブハンドオフは実験的機能で、オプトインです:
+
+```bash
+herdr update --handoff
+herdr --remote workbox --handoff
+```
+
+素の `herdr update` と素の `herdr --remote workbox` は、デフォルトでは通常の再起動/停止フローを使います。
+
+`herdr update --handoff` は Herdr 自身のアップデーターが管理するインストールにのみ適用されます。Homebrew、mise、Nix のインストールはそれぞれのパッケージマネージャーで更新されるため、そこでは `herdr update` は無効化されており、ライブハンドオフは実行できません。
diff --git a/website/src/content/docs/ja/socket-api.mdx b/website/src/content/docs/ja/socket-api.mdx
new file mode 100644
index 00000000..dca7136d
--- /dev/null
+++ b/website/src/content/docs/ja/socket-api.mdx
@@ -0,0 +1,609 @@
+---
+title: ソケット API
+description: スクリプト、ツール、コーディングエージェントから実行中の Herdr サーバーを制御します。
+---
+
+Herdr は、実行中のセッションを調査・制御する必要があるスクリプトやエージェント向けに、ローカルソケット API を公開しています。
+
+ほとんどの自動化は CLI ラッパーから始めるべきです。生のソケット API は、直接のリクエスト/レスポンス制御や長寿命のイベント購読が必要なときだけ使ってください。
+
+## インテグレーション層を選ぶ
+
+| 層 | 用途 |
+| --- | --- |
+| エージェントスキル | ペイン内からの Herdr の使い方をコーディングエージェントに教える。 |
+| CLI ラッパー | シェルスクリプト、シンプルなオーケストレーション、人間によるデバッグ。 |
+| 生のソケット API | カスタムツール、プロトコルクライアント、イベント購読者。 |
+
+これらの層は同じ制御面を共有します。
+
+## 制御できるもの
+
+ソケット API では次のことができます:
+
+- ワークスペースの作成、一覧、フォーカス、名前変更、クローズ
+- タブの作成、一覧、フォーカス、名前変更、クローズ
+- ペインの一覧、調査、分割、入れ替え、フォーカス、リサイズ、名前変更、読み取り、クローズ、入力送信
+- CLI ヘルパーを通じたエージェントの一覧、調査、読み取り、送信、名前変更、フォーカス、起動、アタッチ
+- フックやプラグインからのカスタムエージェント状態の報告
+- イベントの購読と、出力や状態変化の待機
+- 組み込みインテグレーションのインストールとアンインストール
+- サーバーの停止と設定のリロード
+
+## CLI の例
+
+ワークスペースを作成する:
+
+```bash
+herdr workspace create --cwd ~/project --label api
+```
+
+タブを作成する:
+
+```bash
+herdr tab create --label logs
+```
+
+ペインを分割してコマンドを実行する:
+
+```bash
+herdr pane split w1:p1 --direction right
+herdr pane run w1:p2 "npm test"
+```
+
+ペインを調査して並べ替える:
+
+```bash
+herdr pane layout --current
+herdr pane neighbor --direction right --current
+herdr pane resize --direction right --amount 0.1 --current
+herdr pane swap --direction right --current
+herdr pane zoom --on --current
+herdr pane split w1:p1 --direction right --ratio 0.333
+```
+
+エージェントを待つ:
+
+```bash
+herdr wait agent-status w1:p1 --status done
+```
+
+ペインの出力を読む:
+
+```bash
+herdr pane read w1:p2 --source recent --lines 50
+```
+
+## 生のメソッド
+
+生のソケットメソッド名はドット記法を使います:
+
+| 領域 | メソッド |
+| --- | --- |
+| サーバー | `ping`、`server.stop`、`server.reload_config`、`server.agent_manifests`、`server.reload_agent_manifests` |
+| 通知 | `notification.show` |
+| クライアント | `client.window_title.set`、`client.window_title.clear` |
+| ワークスペース | `workspace.create`、`workspace.list`、`workspace.get`、`workspace.focus`、`workspace.rename`、`workspace.close` |
+| Worktree | `worktree.list`、`worktree.create`、`worktree.open`、`worktree.remove` |
+| タブ | `tab.create`、`tab.list`、`tab.get`、`tab.focus`、`tab.rename`、`tab.close` |
+| ペイン | `pane.split`、`pane.swap`、`pane.move`、`pane.zoom`、`pane.layout`、`pane.process_info`、`pane.neighbor`、`pane.edges`、`pane.focus_direction`、`pane.resize`、`pane.list`、`pane.current`、`pane.get`、`pane.rename`、`pane.send_text`、`pane.send_keys`、`pane.send_input`、`pane.read`、`pane.report_agent`、`pane.report_agent_session`、`pane.report_metadata`、`pane.clear_agent_authority`、`pane.release_agent`、`pane.close`、`pane.wait_for_output` |
+| レイアウト | `layout.export`、`layout.apply` |
+| エージェント | `agent.list`、`agent.get`、`agent.read`、`agent.explain`、`agent.send`、`agent.rename`、`agent.focus`、`agent.start` |
+| イベント | `events.subscribe`、`events.wait` |
+| インテグレーション | `integration.install`、`integration.uninstall` |
+| プラグイン | `plugin.link`、`plugin.list`、`plugin.unlink`、`plugin.enable`、`plugin.disable`、`plugin.action.list`、`plugin.action.invoke`、`plugin.log.list`、`plugin.pane.open`、`plugin.pane.focus`、`plugin.pane.close` |
+
+一部の CLI コマンドは、これらのメソッドの便利ラッパーです。たとえば `herdr agent wait` は、エージェントターゲットを解決してからペインのエージェント状態イベントを購読します。
+
+ペイン制御メソッドは `w1:p1` のような公開ペイン id を使います。スキーマ上 `pane_id` が省略可能なメソッドは、省略時にサーバーのアクティブなフォーカス中ペインを使います。`pane.move` は常に送信元の `pane_id` を要求します。
+
+`pane.send_keys` と `pane.send_input.keys` は Herdr のキーコンボ文字列を受け付けます: 通常の印字可能キー、`enter` や `esc` のような特殊キー、`ctrl+h`、`control+j`、`alt+x`、`shift+tab` のような修飾キーコード、`f1` のようなファンクションキー、`minus` や `plus` のような名前付き記号です。`prefix+` のバインド文字列は受け付けません。
+
+```json
+{"id":"req_current","method":"pane.current","params":{"caller_pane_id":"w1:p1"}}
+{"id":"req_layout","method":"pane.layout","params":{"pane_id":"w1:p1"}}
+{"id":"req_neighbor","method":"pane.neighbor","params":{"pane_id":"w1:p1","direction":"right"}}
+{"id":"req_edges","method":"pane.edges","params":{"pane_id":"w1:p1"}}
+{"id":"req_focus","method":"pane.focus_direction","params":{"direction":"right"}}
+{"id":"req_resize","method":"pane.resize","params":{"pane_id":"w1:p1","direction":"right","amount":0.1}}
+{"id":"req_zoom","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"toggle"}}
+{"id":"req_split","method":"pane.split","params":{"direction":"right","ratio":0.333,"env":{"HERDR_ROLE":"tests"}}}
+{"id":"req_process","method":"pane.process_info","params":{"pane_id":"w1:p1"}}
+```
+
+`pane.current` は単一の `PaneInfo` を返します。`caller_pane_id` があるときはそのペインを返します。省略時はアクティブなフォーカス中ペインを返します。
+
+`pane.layout` は、`workspace_id`、`tab_id`、`zoomed`、外側の `area`、`focused_pane_id`、ペインの矩形、分割の矩形/比率を含むタブレイアウトのスナップショットを返します。`pane.neighbor` と `pane.edges` は同じレイアウトスナップショットを含むので、クライアントは非公開のレイアウト状態なしに次の判断を下せます。
+
+`pane.process_info` は、ペインのシェル pid、利用可能な場合はフォアグラウンドプロセスグループ id、そしてプラットフォームが公開している場合は pid、名前、argv/cmdline、cwd を含むフォアグラウンドプロセスを返します。
+
+`layout.export` は移植可能なタブレイアウトツリーを返します。アクティブなタブをエクスポートするには `tab_id` と `pane_id` の両方を省略し、特定のタブなら `tab_id` を、そのペインを含むタブなら `pane_id` を渡します。
+
+```json
+{"id":"req_export","method":"layout.export","params":{"tab_id":"w1:t1"}}
+```
+
+レスポンスには `workspace_id`、`tab_id`、`zoomed`、`focused_pane_id`、`root` が含まれます。`root` は `pane` ノードと `split` ノードの BSP ツリーです。ペインノードは `pane_id`、`label`、`cwd`、argv の `command` を含められます。分割ノードは `direction` (`right` または `down`)、`ratio`、`first`、`second` を使います。
+
+`layout.apply` は宣言的なツリーから新しいタブを作成します。`tab_id` が与えられた場合、Herdr は先に置き換え用のタブを作成してから古いタブを閉じます。これは構造、ラベル、cwd、env、任意の argv コマンドを復元しますが、ライブの PTY、スクロールバック、実行中プロセスは保存しません。
+
+```json
+{
+ "id": "req_apply",
+ "method": "layout.apply",
+ "params": {
+ "workspace_id": "wabc",
+ "tab_label": "dev",
+ "focus": true,
+ "root": {
+ "type": "split",
+ "direction": "right",
+ "ratio": 0.65,
+ "first": {
+ "type": "pane",
+ "label": "editor",
+ "cwd": "/repo"
+ },
+ "second": {
+ "type": "pane",
+ "label": "tests",
+ "cwd": "/repo",
+ "command": ["sh", "-c", "just test"],
+ "env": { "HERDR_ROLE": "tests" }
+ }
+ }
+ }
+}
+```
+
+プロセスを起動するメソッドは `env` オブジェクトを受け付けます。Herdr はそのキー/値ペアを新しく起動されるプロセスにのみ適用します。Herdr は管理下のペインプロセスに `HERDR_SOCKET_PATH`、`HERDR_ENV=1`、`HERDR_WORKSPACE_ID`、`HERDR_TAB_ID`、`HERDR_PANE_ID` も注入します。呼び出し側が与えた環境変数と衝突した場合、Herdr 管理の変数が権威を持ちます。
+
+`pane.swap` は方向指定と明示指定の両方の形式をサポートします:
+
+```json
+{"id":"req_swap_dir","method":"pane.swap","params":{"pane_id":"w1:p1","direction":"right"}}
+{"id":"req_swap_explicit","method":"pane.swap","params":{"source_pane_id":"w1:p1","target_pane_id":"w1:p2"}}
+```
+
+入れ替えは同じタブ内に限られます。分割の形、分割比率、ペイン id、実行中のプロセスを保存します。レスポンスは `type: "pane_swap"` で、`changed`、任意の `reason`、`source_pane_id`、任意の `target_pane_id`、`focused_pane_id`、`layout` を含みます。reason の値は `no_neighbor`、`same_pane`、`not_found`、`cross_tab` です。タブがズームされている場合、入れ替えはズームを維持したまま隠れた全タブレイアウトを変更します。
+
+`pane.move` は、実行中のペインを別のタブ、新しいタブ、または新しいワークスペースに移動します:
+
+```json
+{"id":"req_move_tab","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"tab","tab_id":"w1:t2","target_pane_id":"w1:p3","split":"right","ratio":0.5},"focus":true}}
+{"id":"req_move_new_tab","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"new_tab","workspace_id":"w1","label":"logs"},"focus":true}}
+{"id":"req_move_new_workspace","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"new_workspace","label":"logs","tab_label":"main"},"focus":true}}
+```
+
+既存タブへの移動には `split: "right" | "down"` が必要です。`target_pane_id` は任意で、デフォルトは移動先タブのフォーカス中ペインです。同じタブ内のレイアウト変更は引き続き `pane.swap` です。元のタブへの移動は `reason: "same_tab"` 付きで `changed: false` を返します。ズームされた移動元/移動先タブを含む移動は `reason: "zoomed_tab"` 付きで `changed: false` を返します。
+
+レスポンスは `type: "pane_move"` で、`changed`、任意の `reason`、`previous_pane_id`、`previous_workspace_id`、`previous_tab_id`、移動された `pane`、任意の `source_layout`、`target_layout`、任意の作成されたワークスペース/タブのレコード、任意の閉じられたワークスペース/タブの id、`focused_pane_id` を含みます。ワークスペースをまたぐ移動では、内部のペインとターミナルは生きたまま、移動先ワークスペースで新しい公開ペイン id が割り当てられます。購読者は `pane.moved` を購読できます。Herdr は移動されたターミナルプロセスについて偽のペインの close/create イベントを発行しません。
+
+`pane.zoom` は、対象ペインのタブのズームをトグル、有効化、無効化します:
+
+```json
+{"id":"req_zoom_toggle","method":"pane.zoom","params":{"pane_id":"w1:p1"}}
+{"id":"req_zoom_on","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"on"}}
+{"id":"req_zoom_off","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"off"}}
+```
+
+`pane_id` を省略すると、サーバーのアクティブなフォーカス中ペインが対象になります。レスポンスは `type: "pane_zoom"` で、`changed`、`zoom_changed`、`focus_changed`、任意の `reason`、`pane_id`、`focused_pane_id`、`zoomed`、`layout` を含みます。`changed` は、ズーム状態またはフォーカスのどちらかが変わったときに true です。reason の値は `single_pane`、`already_zoomed`、`already_unzoomed` です。
+
+`notification.show` の CLI ラッパーは次のとおりです:
+
+```bash
+herdr notification show "build failed" --body "api workspace" --position top-left --sound request
+```
+
+設定済みのトースト配信を通じてユーザー通知を表示します:
+
+```json
+{"id":"req_notify","method":"notification.show","params":{"title":"build failed","body":"api workspace","position":"top-left","sound":"request"}}
+```
+
+`title` は必須で、制御文字と連続する空白を除去した後に可視のテキストが残っていなければなりません。`body` は任意です。Herdr は改行、タブ、キャリッジリターン、連続する空白をスペースにまとめてから、通知テキストを `title` は 80 文字、`body` は 240 文字に切り詰めます。サニタイズ後の `title` が空の場合は `invalid_params` を返します。`position` は任意で、`ui.toast.delivery = "herdr"` のときのみ適用されます。デスクトップの位置は Herdr のフレーム全体を基準とし、省略時は `ui.toast.herdr.position` を使います。terminal、system、off の配信では `position` は無視されます。`sound` は任意で `none`、`done`、`request` のいずれかを指定でき、デフォルトは `none` で、通知が表示されたときにのみ再生されます。
+
+レスポンスは何かが表示されたかどうかを報告します:
+
+```json
+{"id":"req_notify","result":{"type":"notification_show","shown":true,"reason":"shown"}}
+```
+
+reason の候補は `shown`、`disabled`、`rate_limited`、`no_foreground_client`、`busy` です。`disabled` は `ui.toast.delivery = "off"` を意味します。`busy` は既存のアプリ内トーストが置き換えられなかったことを意味します。terminal と system の配信は、現在フォアグラウンドでアタッチしている Herdr クライアントを通じたベストエフォートです。
+
+フォアグラウンドクライアントの外側ターミナルウィンドウタイトルを設定またはクリアします:
+
+```json
+{"id":"req_title","method":"client.window_title.set","params":{"title":"herdr api"}}
+{"id":"req_title_clear","method":"client.window_title.clear","params":{}}
+```
+
+`client.window_title.clear` は Herdr のデフォルトタイトルを復元します。レスポンスは `type: "client_window_title"` で、`changed` と、`set`、`cleared`、`no_foreground_client` のいずれかの reason を含みます。
+
+Worktree メソッドは Git チェックアウトを Herdr ワークスペースとして管理します。`worktree.create` はチェックアウトを作成し、新しい `workspace`、`tab`、`root_pane`、`worktree` のレコードを返します。要求されたブランチがローカルに既存ならそれをチェックアウトし、なければ要求されたベースまたは `HEAD` からブランチを作成します。`worktree.open` は既存のチェックアウトを開くか、すでに開いているワークスペースを返します。`worktree.remove` はリンクされた子ワークスペースに対して `git worktree remove` を実行し、ブランチは決して削除しません。
+
+元のワークスペースから worktree を作成する:
+
+```json
+{"id":"req_1","method":"worktree.create","params":{"workspace_id":"w1","branch":"worktree/api","focus":false}}
+```
+
+既存のチェックアウトを開く:
+
+```json
+{"id":"req_2","method":"worktree.open","params":{"workspace_id":"w1","branch":"worktree/api","focus":true}}
+```
+
+リンクされたチェックアウトを削除する:
+
+```json
+{"id":"req_3","method":"worktree.remove","params":{"workspace_id":"2","force":false}}
+```
+
+`worktree.list`、`worktree.create`、`worktree.open` では `workspace_id` と `cwd` は最大どちらか一方だけを使い、両方省略するとアクティブなワークスペースを使います。`worktree.open` では `path` と `branch` のちょうど一方を使います。生のソケットの `cwd` と `path` の値は絶対パスでなければなりません。CLI は相対の `--cwd` と `--path` の値をリクエスト送信前に展開します。ワークスペースが Herdr の worktree グループに属している場合、ワークスペースのレスポンスには任意の `worktree` 出自情報が含まれます。既存のワークスペースが worktree の出自情報を獲得または変更したとき、worktree コマンドは `workspace.updated` を発行することがあります。
+
+worktree コマンドはライフサイクルイベントも発行します。`worktree.create` は `workspace.created`、`tab.created`、`pane.created`、`worktree.created` を発行します。`worktree.open` は `worktree.opened` を発行し、新しい Herdr ワークスペースを開いた場合はワークスペース/タブ/ペインの作成イベントも発行します。`worktree.remove` は `worktree.removed` を発行し、リンクされたワークスペースがまだ開いている場合は `workspace.closed` も発行します。
+
+## プラグイン API
+
+プラグイン API は、実行可能なワークフローツールのための初期のホスト面です。プラグインは `herdr-plugin.toml` マニフェストを持つパッケージです。マニフェストは、共有可能なアクション、イベントフック、ターミナルペインのエントリーポイント、リンクハンドラーを宣言します。アクションとペインはマニフェスト専用です。ランタイムでのアクション登録とランタイムでの argv ペイン作成は v1 の範囲外です。
+
+インストールおよびリンクされたプラグインは再起動をまたいで永続化されます。Herdr は `plugin.link`、`plugin.unlink`、`plugin.enable`、`plugin.disable` の際に、`session.json` の隣に `plugins.json` レジストリファイルを書き込みます。`herdr plugin install` CLI も、Herdr が動作していないときに同じレジストリを書き込み、起動時に自動的に読み込まれます。起動時、Herdr は各マニフェストを元のパスから再読み込みします。ファイルが欠落しているかパースできない場合、エントリは `warnings` フィールド付きで保持され、`plugin.list` がそれを表面化します。
+
+イベントフックの `on` の値は、リンク時に既知の Herdr イベント名と照合されます。認識されない名前はエラーではなく、リンクは成功しますが、返されるプラグイン情報に警告が含まれます (例: `"unknown event 'worktree.craeted'"`)。`plugin.link` と `plugin.list` のレスポンスの `warnings` フィールドを確認してください。
+
+ローカルのプラグインマニフェストをリンクする:
+
+```json
+{"id":"req_plugin_link","method":"plugin.link","params":{"path":"/path/to/plugin","enabled":true}}
+```
+
+`plugin.link` は任意の `source` メタデータも受け付けます。CLI は GitHub からインストールするときにこれを使い、`plugin.list` が出自、要求された ref、解決されたコミット、管理チェックアウトのパスを表示できるようにします:
+
+```json
+{"id":"req_plugin_link","method":"plugin.link","params":{"path":"/managed/plugin/herdr-plugin.toml","enabled":true,"source":{"kind":"github","owner":"ogulcancelik","repo":"herdr-plugin-examples","subdir":"worktree-bootstrap","requested_ref":"main","resolved_commit":"abc123","managed_path":"/data/plugins/github/<managed-checkout>","installed_unix_ms":1780000000000}}}
+```
+
+パスは `herdr-plugin.toml` を含むプラグインディレクトリでも、マニフェストへの直接パスでも構いません。マニフェストの形式は次のとおりです:
+
+```toml
+id = "example.worktree-bootstrap"
+name = "Worktree Bootstrap"
+version = "0.1.0"
+min_herdr_version = "0.7.0"
+description = "Prepare new worktrees"
+platforms = ["linux", "macos", "windows"]
+
+[[build]]
+command = ["bun", "install"]
+
+[[actions]]
+id = "bootstrap"
+title = "Bootstrap worktree"
+contexts = ["workspace"]
+command = ["bun", "run", "bootstrap.ts"]
+
+[[events]]
+on = "worktree.created"
+command = ["bun", "run", "bootstrap.ts"]
+
+[[panes]]
+id = "board"
+title = "Worktree board"
+placement = "overlay"
+command = ["bun", "run", "board.ts"]
+
+[[link_handlers]]
+id = "github-issue"
+title = "Open GitHub issue"
+pattern = "^https://github\\.com/[^/]+/[^/]+/(issues|pull)/[0-9]+$"
+action = "bootstrap"
+```
+
+`min_herdr_version` は必須です。このフィールドが欠落している、無効、または実行中の Herdr バイナリより新しい場合、サーバーはプラグインのリンクを拒否します。
+
+プラグインが対応する OS 識別子 (`linux`、`macos`、`windows`) をトップレベルの `platforms` で宣言してください。ローカル開発では `platforms` の省略が許されます — `plugin.link` は成功しますが、レスポンスに警告が含まれます。個々のビルドコマンド、アクション、イベントフック、ペイン、リンクハンドラーは独自の `platforms` を宣言してプラグインレベルのリストを上書きできます。省略時はプラグインから継承します。実効的な platforms が現在の OS を含まないアクションの呼び出しやペインのオープンは `platform_unsupported` エラーを返します。
+
+リンク済みプラグインの一覧、有効化、無効化、リンク解除:
+
+```json
+{"id":"req_plugin_list","method":"plugin.list","params":{}}
+{"id":"req_plugin_disable","method":"plugin.disable","params":{"plugin_id":"example.worktree-bootstrap"}}
+{"id":"req_plugin_enable","method":"plugin.enable","params":{"plugin_id":"example.worktree-bootstrap"}}
+{"id":"req_plugin_unlink","method":"plugin.unlink","params":{"plugin_id":"example.worktree-bootstrap"}}
+```
+
+アクションはリンクされたマニフェストから解決されます。`plugin.action.list` はインストール済みプラグイン全体のすべてのアクションを返します。絞り込むには `plugin_id` を渡してください。
+
+```json
+{"id":"req_plugin_actions","method":"plugin.action.list","params":{}}
+{"id":"req_plugin_actions_filtered","method":"plugin.action.list","params":{"plugin_id":"example.worktree-bootstrap"}}
+```
+
+`plugin.action.list` は、プラグインレベルの継承を適用した後の各アクションの実効的な `platforms` を返します。
+
+修飾 id または素のアクション id でアクションを呼び出す:
+
+```json
+{"id":"req_plugin_invoke","method":"plugin.action.invoke","params":{"action_id":"example.worktree-bootstrap.bootstrap","context":{"invocation_source":"keybinding"}}}
+```
+
+`plugin.action.invoke` はマニフェストのアクションを解決し、マニフェストのコマンドを起動し、Herdr が構築した呼び出しコンテキストと、開始されたコマンドのログレコードを返します。欠けているコンテキストフィールドは、アクティブなワークスペース、タブ、フォーカス中のペイン、worktree の出自情報、リクエスト id から補完されます。無効化されたプラグインのアクションの呼び出しは `plugin_disabled` エラーを返します。
+
+Herdr は `HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ENV=1`、`HERDR_PLUGIN_ID`、`HERDR_PLUGIN_ROOT`、`HERDR_PLUGIN_CONFIG_DIR`、`HERDR_PLUGIN_STATE_DIR`、`HERDR_PLUGIN_CONTEXT_JSON`、そして利用可能な `HERDR_WORKSPACE_ID`、`HERDR_TAB_ID`、`HERDR_PANE_ID` の値を注入します。アクションコマンドは加えて `HERDR_PLUGIN_ACTION_ID` を受け取ります。イベントフックは `HERDR_PLUGIN_EVENT` と `HERDR_PLUGIN_EVENT_JSON` を、ペインコマンドは `HERDR_PLUGIN_ENTRYPOINT_ID` を受け取ります。
+
+直近のアクションおよびイベントコマンドのログを一覧する:
+
+```json
+{"id":"req_plugin_logs","method":"plugin.log.list","params":{"plugin_id":"example.worktree-bootstrap","limit":20}}
+```
+
+イベントフックは、Herdr が `worktree.created` のような一致するイベント名を発行したときに、有効なインストール済みプラグインに対して実行されます。
+
+v1 には Herdr が管理するプラグインストレージ API はありません。`HERDR_PLUGIN_CONFIG_DIR` と `HERDR_PLUGIN_STATE_DIR` はパスの発見だけを提供します。ファイル、スキーマ、マイグレーション、クリーンアップはプラグインが所有します。
+
+管理されたターミナル UI を開く:
+
+```json
+{"id":"req_plugin_pane","method":"plugin.pane.open","params":{"plugin_id":"example.board","entrypoint":"board","placement":"zoomed","target_pane_id":"w1:p1","env":{"HERDR_ROLE":"board"},"focus":true}}
+```
+
+`plugin.pane.open` は、インストール済みで有効かつプラットフォーム互換のプラグインを要求し、要求されたマニフェストの `[[panes]]` エントリーポイントを argv ベースのターミナルペインとして起動します。マニフェストのペイン `placement` のデフォルトは `overlay` です。リクエストの `placement` は `overlay`、`split`、`tab`、`zoomed` でマニフェストを上書きできます。オーバーレイのペインはアクティブなペインを対象とします。分割とズームのペインは既存のペインを対象とし、タブのペインはワークスペースを対象にできます。ペインは開いた後は通常の Herdr ペインとして振る舞いますが、`plugin.pane.focus` と `plugin.pane.close` はプラグイン API 経由で開かれたペインにのみ作用します。focus は `plugin_pane_focused` を、close は `plugin_pane_closed` を返します。
+
+## ソケットトランスポート
+
+Herdr はローカルソケット上の改行区切り JSON を使います。Unix では Unix ドメインソケットです。Windows では名前付きパイプです。
+
+1 行につき 1 リクエストを送ります:
+
+```json
+{"id":"req_1","method":"ping","params":{}}
+```
+
+成功レスポンスは同じ `id` を含みます:
+
+```json
+{"id":"req_1","result":{"type":"pong"}}
+```
+
+イベント購読は、最初のレスポンスの後も接続を開いたままにします。
+
+## ソケットパス
+
+デフォルトのソケットは Herdr の設定ディレクトリの下にあります。
+
+名前付きセッションは別のソケットを持ちます:
+
+```text
+~/.config/herdr/herdr.sock
+~/.config/herdr/sessions/<name>/herdr.sock
+```
+
+解決順:
+
+1. 明示的な CLI の `--session <name>`
+2. `HERDR_SOCKET_PATH`
+3. `HERDR_SESSION=<name>`
+4. デフォルトセッションのソケット
+
+`HERDR_SOCKET_PATH` は低レベルな上書きにのみ使ってください。
+
+プラグインでは、移植性のある Windows の挙動が必要なときは `HERDR_BIN_PATH` と CLI ラッパーの呼び出しを推奨します。生のソケットクライアントは、プラットフォームネイティブのローカルソケット形式を使う責任を負います。
+
+## エージェント状態の報告
+
+インテグレーションは `pane.report_agent` でエージェント状態を報告します。
+
+```json
+{
+ "id": "req_1",
+ "method": "pane.report_agent",
+ "params": {
+ "pane_id": "w1:p1",
+ "source": "custom:docs",
+ "agent": "docs-bot",
+ "state": "working",
+ "message": "building docs",
+ "custom_status": "indexing"
+ }
+}
+```
+
+`state` は意味的です。wait、通知、ロールアップに影響します。
+
+`custom_status` は表示用です。意味的な挙動を変えずに `indexing` のような短いアクティビティラベルを表示できます。
+
+セッションのみの公式インテグレーションは、`pane.report_agent_session` でネイティブセッション参照を報告します。状態を報告するインテグレーションは、`pane.report_agent` にネイティブセッション参照を含めることもできます。状態に依存しないセッション報告は、wait、通知、ロールアップに影響しません。
+
+```json
+{
+ "id": "req_2",
+ "method": "pane.report_agent_session",
+ "params": {
+ "pane_id": "w1:p1",
+ "source": "herdr:codex",
+ "agent": "codex",
+ "agent_session_id": "..."
+ }
+}
+```
+
+Herdr に保存されたネイティブセッション参照があるとき、`pane.get`、`pane.list`、`agent.get`、`agent.list` は読み取り専用の `agent_session` オブジェクトを公開します:
+
+```json
+{
+ "agent_session": {
+ "source": "herdr:codex",
+ "agent": "codex",
+ "kind": "id",
+ "value": "..."
+ }
+}
+```
+
+ネイティブセッション参照が保存されていない場合、このフィールドは省略されます。
+
+`pane.get`、`pane.list`、`agent.get`、`agent.list` は、ペインの PTY を現在制御しているプロセスの cwd を解決できるときに `foreground_cwd` も公開します。既存の `cwd` フィールドは、ラベル、follow-cwd 挙動、復元されたセッション状態に使われるペイン/ワークスペースの cwd のままです。
+
+ユーザーフックが Herdr インテグレーションからライフサイクル状態を奪わずに表示をカスタマイズしたいときは `pane.report_metadata` を使ってください。
+
+```json
+{
+ "id": "req_2",
+ "method": "pane.report_metadata",
+ "params": {
+ "pane_id": "w1:p1",
+ "source": "user:claude-title",
+ "agent": "claude",
+ "title": "Refactor auth middleware",
+ "display_agent": "Claude: auth",
+ "custom_status": "refactor auth",
+ "state_labels": {
+ "working": "refactoring auth",
+ "idle": "ready",
+ "done": "review ready"
+ },
+ "ttl_ms": 3600000
+ }
+}
+```
+
+メタデータ報告は表示専用です。有効なメタデータは、ペインのタイトル、表示されるエージェント名、コンパクトなアクティビティラベル、可視の状態ラベルを上書きできます。`working`、`blocked`、`idle`、wait、通知、ロールアップは引き続き意味的な状態から得られます。エージェントネイティブのセッション復元は、保存された公式セッション参照から得られます。`agent` は権威あるエージェントラベルに対する任意のガードで、`applies_to_source` はアクティブなライフサイクル権威ソースに対する任意のガードです。表示名を変えるには `display_agent` を使います。`state_labels` のキーは `idle`、`working`、`blocked`、`done`、`unknown` のいずれかでなければなりません。ひとつの表示上書きを取り除くには、同じ `source` で `clear_custom_status: true` のようなクリアフィールドを使ってください。
+
+表示テキストは保存前に正規化されます。Herdr は前後の空白を取り除き、制御文字を除去し、`custom_status` を 32 文字に、`title`、`display_agent`、各状態ラベルを 80 文字に制限します。正規化後に空になった値は無視されます。
+
+`source` と `applies_to_source` はソース識別子です。80 文字以下で、ASCII の英字、数字、コロン、ドット、アンダースコア、ハイフンのみを含められます。
+
+短寿命のメタデータには `ttl_ms` を使ってください。`1` から `86400000` ミリ秒の間でなければなりません。置き換え・クリア・ペインのクローズまで残るべきメタデータでは省略します。TTL が切れると、Herdr はそのソースのメタデータを削除し、可視のペイン表示が変わった場合は表示変更イベントを発行します。
+
+フックが順不同で更新を送る可能性がある場合は `seq` を使ってください。同じ `source` について、最後に受理されたシーケンス以下のシーケンス番号を持つ報告は、API には受理されますがペイン状態には無視されます。
+
+## イベント購読
+
+長寿命のストリームが必要なときはイベントを購読します:
+
+```json
+{
+ "id": "sub_1",
+ "method": "events.subscribe",
+ "params": {
+ "subscriptions": [
+ { "type": "pane.agent_status_changed", "pane_id": "w1:p1", "agent_status": "blocked" }
+ ]
+ }
+}
+```
+
+最初のレスポンスは購読の確認応答です。以降の行はプッシュされるイベントです。
+
+ワークスペースのイベント購読には `workspace.created`、`workspace.updated`、`workspace.renamed`、`workspace.closed`、`workspace.focused` があります。ワークスペースイベントは Herdr の UI/ランタイムのライフサイクルを記述します。ワークスペースが worktree グループに属している場合、`workspace.created` は任意の `workspace.worktree` 出自情報を含みます。削除前に Herdr がまだ識別できる場合、`workspace.closed` は最終的な `workspace` スナップショットを含みます。
+ペインのイベント購読には `pane.created`、`pane.closed`、`pane.focused`、`pane.moved`、`pane.exited`、`pane.agent_detected`、`pane.output_matched`、`pane.agent_status_changed` があります。
+
+worktree のイベント購読には `worktree.created`、`worktree.opened`、`worktree.removed` があります。worktree イベントは Git チェックアウトのライフサイクルを記述します。`worktree.created` は開かれた `workspace` と作成された `worktree` を含みます。`worktree.opened` は対象の `workspace`、開かれた `worktree`、`already_open` を含みます。`worktree.removed` は `workspace_id`、削除された `worktree`、`forced` を含みます。
+
+ライフサイクルイベントには `events.subscribe` を使ってください。ワンショットの wait がサポートされる場合、専用の wait ヘルパーが別途ドキュメント化されます。
+
+## ペインの読み取り
+
+プロトコルクライアントを書いているのでなければ、CLI 経由で `pane.read` を使ってください。
+
+```bash
+herdr pane read w1:p1 --source visible --lines 80
+herdr pane read w1:p1 --source recent --lines 120
+herdr pane read w1:p1 --source recent-unwrapped --lines 120
+herdr pane read w1:p1 --source detection
+```
+
+`recent-unwrapped` はソフト折り返しを無視するのでログに便利です。
+`detection` は、エージェントのスクリーン検出が使う下部バッファのスナップショットを返します。
+
+## 状態の待機
+
+エージェントとスクリプトの協調には wait を使います。
+
+```bash
+herdr wait agent-status w1:p1 --status done
+herdr wait agent-status w1:p1 --status blocked
+```
+
+エージェントの wait は、任意のコマンドの完了ではなく意味的な状態を観測します。
+
+## レスポンスの形式
+
+成功レスポンスは次のようになります:
+
+```json
+{
+ "id": "req_1",
+ "result": {
+ "type": "pane_info",
+ "pane": {
+ "pane_id": "w1:p1",
+ "terminal_id": "term_abc123",
+ "workspace_id": "w1",
+ "tab_id": "w1:t1",
+ "focused": true,
+ "agent_status": "working",
+ "revision": 42
+ }
+ }
+}
+```
+
+`server.agent_manifests` は、ルールをリロードせずに、アクティブなエージェント検出マニフェストのソースとリモート更新の診断情報を返します:
+
+```json
+{
+ "id": "req_1",
+ "result": {
+ "type": "agent_manifest_status",
+ "last_check_unix": 1781043522,
+ "last_result": "checked",
+ "manifests": [
+ {
+ "agent": "cursor",
+ "source": "/home/me/.config/herdr/agent-detection/cursor.toml",
+ "source_kind": "local override",
+ "active_version": "2026.06.10.1",
+ "cached_remote_version": "2026.06.10.1",
+ "local_override_shadowing_remote": true,
+ "remote_update_result": "current"
+ }
+ ]
+ }
+}
+```
+
+`last_check_unix`、`last_result`、`active_version`、`cached_remote_version`、`remote_update_result`、`remote_update_error`、`remote_last_checked_unix`、`warning` のようなフィールドは、利用できないときは省略されます。`server.reload_agent_manifests` は、メモリ内のルールキャッシュをリロードした後、同じ `manifests` の項目形式を持つ `agent_manifest_reload` を返します。
+
+`agent.explain` は、サーバーのアクティブなマニフェストキャッシュを使って、対象ペインの検出スナップショットを実行中のサーバーで評価します:
+
+```json
+{
+ "id": "req_2",
+ "method": "agent.explain",
+ "params": { "target": "w1:p1" }
+}
+```
+
+レスポンスには `herdr agent explain --json` が出力するのと同じ explain オブジェクトが含まれます: 最終状態、マニフェストのソースとバージョン、マッチしたルール、評価されたルールの証拠、スキップ状態の理由、idle フォールバックの理由、そして完全なライフサイクルフック権威によってスクリーンルールが権威でなくなったときの `screen_detection_skip_reason` です。
+
+クライアントには `agent.explain` をサポートする実行中のサーバーが必要です。Herdr のアップグレード後は、このメソッドに頼る前にサーバーを再起動するかライブハンドオフしてください。
+
+エラーは次のようになります:
+
+```json
+{
+ "id": "req_1",
+ "error": {
+ "code": "not_found",
+ "message": "pane not found"
+ }
+}
+```
+
+## プロトコルの安定性
+
+Herdr にはクライアント/サーバー互換性のためのプロトコルバージョンがあります。プロトコルの変更は、リリースの互換性を念頭にレビューされます。
+
+新しい挙動に依存する前に、`ping` または `herdr status` でサーバーのプロトコルを確認してください。未知のフィールドは寛容に扱ってください。
diff --git a/website/src/content/docs/ja/windows-beta.mdx b/website/src/content/docs/ja/windows-beta.mdx
new file mode 100644
index 00000000..9d282a70
--- /dev/null
+++ b/website/src/content/docs/ja/windows-beta.mdx
@@ -0,0 +1,100 @@
+---
+title: Windows ベータ
+description: ネイティブ Windows 対応の状況、サポートされるワークフロー、既知の制限。
+---
+
+ネイティブ Windows 対応は実験的ベータです。
+
+Windows 上の Herdr は、Herdr が本来前提としていた Unix の PTY モデルではなく、ConPTY と Windows のプロセス/ランタイム挙動を使います。Herdr の機能には Windows にきれいに対応付くものもあれば、そうでないものもあります。このプレビューは、すべての Linux/macOS 機能が Windows で完全にサポートされることを約束するものではありません。
+
+ベータの目的は実際の使用から学ぶことです: インストールの成功率、ペインの信頼性、エージェントのワークフロー、バグの量、不足している機能、そして Windows ユーザーが Herdr から十分な価値を得られているかどうか。そのフィードバックに基づき、Windows 対応は安定版に昇格するか、成熟するまでプレビュー限定のままか、メンテナンスコストに見合わなければ縮小される可能性があります。
+
+ネイティブ Windows ベータビルドは PowerShell でインストールします:
+
+```powershell
+powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
+```
+
+Windows ベータビルドはプレビューチャンネルでのみ提供されます。Windows インストーラーはデフォルトでプレビューを使い、Herdr の設定に `channel = "preview"` を書き込み、リリースを `%USERPROFILE%\.herdr\packages\standalone\releases` に保存し、`%LOCALAPPDATA%\Programs\Herdr\bin` を現在のリリースに向け、実行中のプロセスがアップデートを妨げないよう少数の古いリリースを保持します。
+
+内部ベータテスト向けに、`HERDR_MANIFEST_URL` でインストーラーを Herdr の安定版/プレビューマニフェストではなくカスタムマニフェストに向けられます。
+
+## ベータでサポート
+
+| 機能 | 状況 |
+| --- | --- |
+| ローカル永続セッション | ベータ |
+| ConPTY によるネイティブペイン | ベータ |
+| Windows Terminal / PowerShell アプリからのアタッチ | ベータ |
+| `cmd.exe` ペイン | ベータ |
+| 起動時 cwd とワークスペースラベル | ベータ |
+| ペイン起動時の cwd | ベータ |
+| エージェントコマンドの発見 | ベータ |
+| エージェントのセルフレポートインテグレーション | ベータ |
+| エージェントのプロセスツリー検出 | ベータ |
+| 既知の cwd からの Git/worktree 検出 | ベータ |
+| プラグイン | プレビュー |
+| ペイン画面履歴 | ベータ |
+| ネストされた起動のオーバーライド | ベータ |
+
+Windows のエージェントプロセス検出は、ペインのシェルの子孫プロセスをスキャンし、直接のエージェントと一般的なコマンドラッパーを認識します。Codex、Claude などのエージェントには有用ですが、Unix のフォアグラウンドプロセスグループ検出と同じものではありません。
+
+プラグインは、プレビューとしてマニフェストのプラットフォームに `windows` をサポートします。GitHub インストール、ローカルリンク、ビルドコマンド、アクション、イベント、プラグインペインは Windows ではベストエフォートです。コマンドは argv 形式で Windows 互換である必要があります。`npm`、`bun`、`node` のような Node パッケージの shim は `PATH` にあれば動作するはずですが、`sh` や Bash を使う Unix 専用の例には Windows 向けの代替が必要です。プラットフォームフィルターは、未サポートのビルドコマンドをスキップし、未サポートのアクションやペインには `platform_unsupported` を返します。
+
+## 部分的なサポート
+
+| 機能 | 状況 |
+| --- | --- |
+| シェルで `cd` した後のライブ cwd | 部分的 |
+| シェルインテグレーション/OSC7 によるライブ cwd | ベータ |
+| エージェントへのクリップボード画像貼り付け | 未検証 |
+| CJK の隠れカーソル表示 | ベータ |
+| Kitty graphics のレンダリング | 未検証 |
+
+Herdr はペインを正しいディレクトリで起動でき、Herdr を起動したディレクトリから最初のワークスペースを作成できます。起動後の PowerShell のディレクトリ変更は別問題です: Herdr が調べられるプロセスのフィールドは、その後の論理的な `cd` の変化を確実には追跡しません。ライブ cwd の報告には Herdr インテグレーションかプロンプトのシェルインテグレーションを使ってください。
+
+Windows Terminal は特定のエージェント向けに画像貼り付け経路をサポートしているかもしれませんが、Herdr 自身のクリップボード画像リーダーはまだ Windows に配線されていません。Windows のクリップボードブリッジが実装・テストされるまで、`alt+v` の画像貼り付けは未検証として扱ってください。リモートクリップボードの画像ブリッジは別機能で、引き続き Unix/macOS の `herdr --remote` に紐づいています。
+
+Kitty graphics は実験的なままで、まだ Windows でのサポートを謳っていません。Windows Terminal での画像レンダリングを特にテストしているのでない限り、`experimental.kitty_graphics = false` のままにしてください。
+
+## コピーと貼り付け
+
+Herdr のペインテキストコピーは Windows ベータで動作します。ペイン内でテキストをドラッグ選択すると Herdr 経由でコピーされます。
+
+テキストの貼り付けには Windows Terminal で `ctrl+shift+v` を使ってください。複数行テキストの貼り付けはブラケット付きなので、シェルやエージェントのプロンプトは各行を個別に送信せず、ひとつの貼り付けとして受け取ります。`shift` を押しながら右クリックすると、クリックを Herdr に送らずに外側ターミナルの貼り付けアクションを使えます。
+
+## Windows ベータで未サポート
+
+| 機能 | 状況 |
+| --- | --- |
+| ダイレクトターミナルアタッチ | 未サポート |
+| Windows バイナリからの `herdr --remote` | 未サポート |
+| ライブサーバーハンドオフ | 未サポート |
+| Unix ファイルディスクリプタのハンドオフ | 未サポート |
+| Unix フォアグラウンドプロセスグループ | 未サポート |
+| リモートクリップボード画像ブリッジ | 未サポート |
+| プレフィックスによる入力ソース切り替え | 未サポート |
+| 署名済みバイナリ / SmartScreen 回避 | 未サポート |
+
+Windows からのリモート作業は、サーバーに SSH してそこで `herdr` を実行してください:
+
+```powershell
+ssh you@server
+herdr
+```
+
+このモードでは Herdr はリモートホスト上で動きます。ネイティブ Windows の `herdr --remote` はベータの範囲外です。
+
+Windows のアップデートは Windows インストーラー経由で行われ、バージョン付きインストールジャンクションを更新します。アップデート後は実行中の Herdr セッションを再起動してください。ライブハンドオフは Unix 専用です。
+
+## Windows ベータの問題を報告する
+
+以下を含めてください:
+
+- Herdr のバージョン。
+- Windows のバージョン。
+- ターミナルアプリ。
+- シェル (PowerShell、cmd など)。
+- 名前付き `HERDR_SESSION` を使っていたかどうか。
+- 関連する Herdr のログ。
+- 正確な再現手順。
diff --git a/website/src/content/docs/zh-cn/agent-skill.mdx b/website/src/content/docs/zh-cn/agent-skill.mdx
new file mode 100644
index 00000000..a7657053
--- /dev/null
+++ b/website/src/content/docs/zh-cn/agent-skill.mdx
@@ -0,0 +1,65 @@
+---
+title: 智能体技能文件
+description: 为 Claude Code 或其他编程智能体安装 Herdr 使用说明。
+---
+
+Herdr 提供了一个可复用的智能体技能文件: [`SKILL.md`](https://github.com/ogulcancelik/herdr/blob/master/SKILL.md)。
+
+把这个文件安装到任何支持可复用技能或自定义指令的编程智能体中。这份技能教智能体如何在 Herdr 窗格内部控制 Herdr。
+
+Herdr 还提供了另一份用途不同的指南: [`herdr.dev/agent-guide.md`](https://herdr.dev/agent-guide.md),用于让智能体帮助人类学习、安装或排查 Herdr。技能是给操作 Herdr 的智能体用的;指南是给教人类的智能体用的。
+
+## 这份技能做什么
+
+这份技能告诉智能体: 当 `HERDR_ENV=1` 已设置时,使用 `herdr` CLI。这意味着智能体运行在 Herdr 管理的窗格内,可以安全地与本地 Herdr socket 通信。
+
+安装技能后,智能体可以:
+
+- 查看工作区、标签页、窗格和相邻的智能体
+- 分割窗格并在不抢占焦点的情况下运行命令
+- 读取窗格输出和最近的日志
+- 等待服务器、测试或另一个智能体完成
+- 在相邻窗格中启动辅助智能体
+
+这份技能不是独立的应用或服务,它只是一份给智能体看的 markdown 指令文件。
+
+## 安装
+
+用 `npx skills` 安装技能:
+
+```bash
+npx skills add ogulcancelik/herdr --skill herdr -g
+```
+
+`-g` 参数为受支持的智能体全局安装。省略 `-g` 则安装到当前项目。
+
+以仓库中的副本作为手动兜底和事实来源:
+
+```text
+https://github.com/ogulcancelik/herdr/blob/master/SKILL.md
+```
+
+对于有技能系统的智能体,把这个文件安装为名为 `herdr` 的技能。对于没有技能系统的智能体,把文件内容粘贴到智能体的项目指令或用户指令中。
+
+安装完成后,在 Herdr 内启动智能体:
+
+```bash
+herdr
+claude
+```
+
+也可以在 Herdr 窗格里使用任何其他编程智能体。重点是智能体进程要运行在 Herdr 内部,这样 `HERDR_ENV=1` 才可用。
+
+## 安全规则
+
+这份技能以一条护栏开头: 如果 `HERDR_ENV=1` 未设置,智能体应当停下来,并说明自己没有运行在 Herdr 管理的窗格内。
+
+这可以防止 Herdr 外部的智能体试图控制一个不属于它的会话。
+
+## 面向智能体的参考
+
+完整的命令指南就在技能文件本身。它涵盖窗格 ID、`pane split`、`pane run`、`pane read`、`wait output`、`wait agent-status`、工作区和标签页命令,以及协作配方。
+
+在这里阅读源文件:
+
+[在 GitHub 上打开 `SKILL.md` →](https://github.com/ogulcancelik/herdr/blob/master/SKILL.md)
diff --git a/website/src/content/docs/zh-cn/agents.mdx b/website/src/content/docs/zh-cn/agents.mdx
new file mode 100644
index 00000000..f8db7a41
--- /dev/null
+++ b/website/src/content/docs/zh-cn/agents.mdx
@@ -0,0 +1,163 @@
+---
+title: 智能体
+description: 了解 Herdr 能检测什么、智能体状态如何工作,以及集成如何改进它。
+---
+
+Herdr 为同时运行多个编程智能体而生。每个智能体都待在一个真实的终端窗格里,shell、日志、提示符和运行中的进程都完好无损。Herdr 跟踪哪些窗格里有智能体,把它们的状态汇总到标签页和工作区,让你直接跳到需要关注的窗格,而不是手动轮询每个终端。
+
+## 受支持的智能体
+
+常见编程智能体开箱即用地支持自动检测。重要的区别不在于 Herdr 能不能看到某个智能体,而在于允许哪个信号来决定 `idle`、`working` 和 `blocked`。
+
+| 智能体 | 状态权威 | 集成角色 |
+| --- | --- | --- |
+| Pi | 安装后为生命周期钩子;否则为屏幕清单 | 状态与会话 |
+| OMP | 安装后为生命周期钩子 | 状态 |
+| GitHub Copilot CLI | 屏幕清单 | 会话 |
+| Devin CLI | 屏幕清单 | 会话 |
+| Kimi Code CLI | 安装后为生命周期钩子;否则为屏幕清单 | 状态与会话 |
+| Hermes Agent | 安装后为生命周期钩子;否则为屏幕清单 | 状态与会话 |
+| Qoder CLI | 屏幕清单 | 会话 |
+| Droid | 屏幕清单 | 会话 |
+| OpenCode | 安装后为生命周期插件;否则为屏幕清单 | 状态与会话 |
+| Kilo Code CLI | 安装后为生命周期插件;否则为屏幕清单 | 状态与会话 |
+| Claude Code | 屏幕清单 | 会话 |
+| Codex | 屏幕清单 | 会话 |
+| Cursor Agent CLI | 屏幕清单 | 会话 |
+| Amp | 屏幕清单 | 无 |
+| Grok CLI | 屏幕清单 | 无 |
+| Antigravity CLI | 屏幕清单 | 无 |
+| Kiro CLI | 屏幕清单 | 无 |
+
+可检测但测试较少: Gemini CLI 和 Cline。不受支持的智能体仍然可以作为普通终端进程正常运行,只是在你添加集成或通过 socket API 上报状态之前,可能得不到丰富的状态。
+
+## 状态权威
+
+Herdr 首先检测每个窗格的前台进程。之后,每个窗格有且只有一个状态权威。
+
+对于具备完整生命周期钩子的智能体,当集成已安装并在为运行中的窗格主动上报时,集成就是权威。Herdr 用这些钩子上报来决定 `idle`、`working`、`blocked` 和会话身份。对同一个生命周期权威,它不会再并行运行屏幕清单兜底。这样可以避免出现两个相互竞争的事实来源。
+
+对于没有完整生命周期钩子的智能体,Herdr 识别前台进程,并读取实时的底部缓冲区屏幕快照。它对该快照评估 TOML 清单,来判定 `idle`、`working` 和 `blocked`。对于会发出这些信号的智能体,清单也可以把终端标题和进度 (OSC) 序列作为检测证据;当这些证据不存在时,屏幕规则独自承担检测。
+
+屏幕快照来自窗格缓冲区最近的底部,而不是滚动后的视口。即使你在 Herdr 里向上翻页,检测仍然跟随底部的实时智能体 UI。
+
+Claude Code、Codex、GitHub Copilot CLI、Droid、Qoder CLI 和 Cursor Agent CLI 的集成有意不作为生命周期权威。它们为恢复提供原生会话身份,但它们的钩子并不覆盖整个生命周期,可能漏掉权限审批结果、Esc 中断或其他状态转换。对这些智能体,Herdr 仍然使用屏幕清单检测。
+
+## 虚拟机与沙箱包装器
+
+在 Linux 上,VM、Bubblewrap 或 `fence` 之类的包装器可能把真实的智能体进程从宿主的 `/proc` 中隐藏起来。在命令上设置 `HERDR_AGENT=<agent>`,例如 `HERDR_AGENT=claude fence -- claude`,告诉 Herdr 该使用哪个已有智能体的屏幕清单。这个提示的作用范围只限于那个前台进程;除非所有继承它的前台进程都应被视为该智能体,否则不要在 shell 里全局 export。
+
+## blocked 状态
+
+对屏幕清单类智能体,blocked 检测刻意从严。只有当实时底部缓冲区快照匹配已知可见的审批、提问或权限 UI 时,Herdr 才标记 `blocked`。对已知智能体,如果没有任何清单规则匹配,Herdr 会回退到 `idle`,并在 explain 输出中把该回退标记为 `default_known_agent_idle_fallback`。
+
+这意味着不常见的新智能体提示可能一开始显示为 `idle` 而不是 `blocked`,直到 Herdr 学会那种屏幕形态。这些交互不会让 Herdr 发送输入或执行破坏性操作;它们只影响可见状态和等待。
+
+## 检测清单
+
+内置清单打包在 Herdr 内部。Herdr 还会向 herdr.dev 检查远程清单更新,并自动应用有效的按智能体规则更新,不需要重启 Herdr。远程清单存放在 Herdr 的状态目录中。设置 `[update] manifest_check = false` 可以禁用后台远程清单检查。
+
+本地覆盖可以从平台配置目录替换远程或内置清单:
+
+```text
+~/.config/herdr/agent-detection/<agent>.toml
+```
+
+本地覆盖始终优先。没有本地覆盖时,Herdr 在缓存的远程清单和运行中二进制文件内置的清单之间,选择更新且兼容的那个。在调试构建上,同一个配置助手可能使用 `herdr-dev` 之类的开发目录。无效的覆盖文件会被忽略并给出警告,Herdr 会对该智能体回退到缓存的远程或内置清单。
+
+远程清单只为 Herdr 已经知道如何识别的智能体修补检测规则。添加全新的智能体仍然需要更新 Herdr 二进制文件,以获得进程检测、标签和集成行为。
+
+运行中的服务器在启动时把生效的清单加载进内存。自动的远程清单更新会在写入新规则后重新加载该内存缓存。运行 `herdr server update-agent-manifests` 可以立即拉取远程清单更新并重载运行中的服务器。手动编辑本地覆盖后,重启 Herdr 或运行 `herdr server reload-agent-manifests` 把文件应用到运行中的服务器。
+
+当某个窗格显示了错误状态时,用 `herdr agent explain`:
+
+```bash
+herdr agent explain <target>
+herdr agent explain --file screen.txt --agent codex --json
+```
+
+实时 explain 由运行中的服务器评估,因此反映的是生效的清单缓存。explain 输出包括: 智能体、最终状态、屏幕检测是否被完整生命周期权威跳过、清单来源和版本、缓存的远程版本、本地覆盖的遮蔽情况、远程更新状态、匹配的规则、可见证据标志、已评估规则的匹配器和区域证据、转写查看器的跳过更新原因,以及没有规则匹配时的 idle 回退原因。
+
+Herdr 可以在 tmux 作为外层终端环境时运行。智能体检测不会检查在 Herdr 窗格内启动的 tmux 会话。如果某个 shell 框架在 Herdr 内自动进入 tmux,Herdr 看到的窗格进程就是 `tmux`,而不是它背后的智能体。
+
+## 状态汇总
+
+侧边栏会把状态向上汇总。
+
+一个 blocked 的智能体会让它的窗格、标签页和工作区看起来是 blocked。一个 working 的智能体会让工作区看起来处于活跃状态。一个 done 的智能体在你查看之前会一直保持可见。
+
+这就是 Herdr 的主要工作流: 启动多个智能体,让它们并行工作,用侧边栏看哪个项目需要决策、哪个还在运行、哪个已经可以审阅。
+
+## 直接集成
+
+为你使用的每个智能体安装集成;它让 Herdr 获得钩子或插件上报,而不是只靠屏幕检测:
+
+```bash
+herdr integration install claude
+herdr integration status
+```
+
+每个受支持的智能体都有自己的集成名称和行为。按智能体的细节和完整安装列表见[集成](/zh-cn/docs/integrations/)。
+
+## 自定义智能体标签
+
+你可以重命名智能体目标的显示名:
+
+```bash
+herdr agent rename w1:p1 reviewer
+herdr agent rename reviewer --clear
+```
+
+目标可以是终端 ID、唯一的智能体名称、检测到或上报的智能体标签,以及旧式窗格 ID。
+
+## 自定义状态标签
+
+集成可以上报一个视觉状态标签,而不改变语义状态。
+
+```bash
+herdr pane report-agent w1:p1 \
+ --source custom:indexer \
+ --agent docs-bot \
+ --state working \
+ --custom-status indexing
+```
+
+`state` 控制等待、通知和汇总。`custom-status` 只是显示文本。
+
+## 从 CLI 启动智能体
+
+当你希望一个终端被当作智能体目标时,使用 `herdr agent ...` 命令。智能体目标会出现在 `agent list` 中,可以按智能体名称读取或发送输入,可以按智能体状态等待,也可以被直接附加。
+
+从脚本向 Herdr 中启动一个智能体:
+
+```bash
+herdr agent start reviewer --cwd ~/project --split right -- pi
+```
+
+也可以把该智能体放进特定的工作区或标签页:
+
+```bash
+herdr agent start docs --workspace w1 --tab w1:t1 -- claude
+```
+
+普通终端、服务器、测试、shell 和底层终端输入请使用 `herdr pane ...` 命令。例如跑 `cargo test` 用 `pane split` 和 `pane run`,而不是 `agent start`,除非那个终端就是有意要当作智能体目标。
+
+## 直接附加到智能体
+
+把当前终端附加到某一个智能体终端,而不是完整的 Herdr UI:
+
+```bash
+herdr agent attach reviewer
+```
+
+用 `ctrl+b q` 分离。用 `ctrl+b ctrl+b` 发送字面的 `ctrl+b`。
+
+用鼠标滚轮或普通的 page up/page down 滚动。正常输入会跳回底部。
+
+如果另一个直接附加客户端已经拥有输入,用 `--takeover`:
+
+```bash
+herdr agent attach reviewer --takeover
+```
+
+想对非智能体终端获得相同的直接附加行为时,用 `herdr terminal attach <terminal_id>`。
diff --git a/website/src/content/docs/zh-cn/cli-reference.mdx b/website/src/content/docs/zh-cn/cli-reference.mdx
new file mode 100644
index 00000000..0c23adec
--- /dev/null
+++ b/website/src/content/docs/zh-cn/cli-reference.mdx
@@ -0,0 +1,356 @@
+---
+title: CLI 参考
+description: 用于会话、工作区、标签页、窗格、通知、智能体、等待、集成和状态的 Herdr 命令。
+---
+
+Herdr 的 CLI 通过与集成和智能体相同的本地 socket API 与运行中的服务器通信。
+
+大多数命令输出 JSON 响应。需要确定性自动化时,从脚本中使用它们。
+
+## 启动与状态
+
+```bash
+herdr # 启动或连接默认会话
+herdr --session work # 启动或连接命名会话
+herdr --remote workbox # 通过 SSH 连接,使用本地按键绑定
+herdr --remote workbox --remote-keybindings server
+herdr --remote workbox --handoff
+herdr --no-session # 单进程逃生舱
+herdr --default-config # 打印默认配置
+herdr update # 从配置的通道下载并安装
+herdr update --handoff # 对受支持的运行中服务器启用实时交接
+herdr channel show # 打印 stable 或 preview
+herdr channel set preview # 启用预览构建
+herdr channel set stable # 把 Linux/macOS 直接安装切回稳定版
+herdr --version # 打印版本
+```
+
+状态命令:
+
+```bash
+herdr status
+herdr status server
+herdr status client
+```
+
+## 服务器
+
+```bash
+herdr server
+herdr server stop
+herdr server reload-config
+herdr server agent-manifests [--json]
+herdr server update-agent-manifests [--json]
+herdr server reload-agent-manifests
+```
+
+`herdr server` 显式运行无界面服务器,适合被监管或服务式的部署。`reload-config` 在不重启窗格的情况下应用可重载设置。`agent-manifests` 显示生效的智能体检测清单来源、缓存的远程版本和最近的远程更新结果。`update-agent-manifests` 立即拉取远程清单更新,重载到运行中的服务器,并打印更新后的清单状态;要原始状态响应就加 `--json`。`reload-agent-manifests` 在编辑本地覆盖后,把智能体检测清单重载到运行中的服务器。
+
+## 通知
+
+```bash
+herdr notification show <title> [--body TEXT] [--position top-left|top-right|bottom-left|bottom-right] [--sound none|done|request]
+```
+
+`notification show` 使用配置的 `[ui.toast]` 投递方式。`--position` 只影响 Herdr 应用内的 toast。`--sound` 默认为 `none`;`done` 和 `request` 只在通知实际显示时播放已有的完成音和需要关注音。
+
+## 会话
+
+```bash
+herdr session list [--json]
+herdr session attach <name>
+herdr session stop <name> [--json]
+herdr session delete <name> [--json]
+```
+
+需要显式停止默认会话时,把会话名写成 `default`。
+
+## 工作区
+
+```bash
+herdr workspace list
+herdr workspace create [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [--no-focus]
+herdr workspace get <workspace_id>
+herdr workspace focus <workspace_id>
+herdr workspace rename <workspace_id> <label>
+herdr workspace close <workspace_id>
+```
+
+不抢占焦点地创建工作区:
+
+```bash
+herdr workspace create --cwd ~/project --label api --no-focus
+```
+
+## Worktree
+
+```bash
+herdr worktree list [--workspace ID | --cwd PATH] [--json]
+herdr worktree create [--workspace ID | --cwd PATH] [--branch NAME] [--base REF] [--path PATH] [--label TEXT] [--focus] [--no-focus] [--json]
+herdr worktree open [--workspace ID | --cwd PATH] (--path PATH | --branch NAME) [--label TEXT] [--focus] [--no-focus] [--json]
+herdr worktree remove --workspace ID [--force] [--json]
+```
+
+worktree 是带有 Git 检出来源信息的普通 Herdr 工作区。`worktree create` 创建一个 Git worktree 检出,作为工作区打开,并与父仓库工作区分到一组。如果 `--branch` 指向已有的本地分支,Herdr 检出它;否则从 `--base` 或 `HEAD` 创建分支。没有 `--path` 时,Herdr 在 `<worktrees.directory>/<repo>/<branch-slug>` 下创建检出。
+
+`workspace close` 只关闭 Herdr 状态。`worktree remove` 是显式的检出删除路径;它运行 `git worktree remove`,从不删除分支,并在 Git 拒绝脏检出时要求 `--force`。
+
+## 标签页
+
+```bash
+herdr tab list [--workspace <workspace_id>]
+herdr tab create [--workspace <workspace_id>] [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [--no-focus]
+herdr tab get <tab_id>
+herdr tab focus <tab_id>
+herdr tab rename <tab_id> <label>
+herdr tab close <tab_id>
+```
+
+## 窗格
+
+```bash
+herdr pane list [--workspace <workspace_id>]
+herdr pane current [--pane ID|--current]
+herdr pane get <pane_id>
+herdr pane layout [--pane ID|--current]
+herdr pane process-info [--pane ID|--current]
+herdr pane neighbor --direction left|right|up|down [--pane ID|--current]
+herdr pane edges [--pane ID|--current]
+herdr pane focus --direction left|right|up|down [--pane ID|--current]
+herdr pane resize --direction left|right|up|down [--amount FLOAT] [--pane ID|--current]
+herdr pane zoom [<pane_id>|--pane ID|--current] [--toggle|--on|--off]
+herdr pane rename <pane_id> <label>|--clear
+herdr pane split [<pane_id>|--pane ID|--current] --direction right|down [--ratio FLOAT] [--cwd PATH] [--env KEY=VALUE] [--focus] [--no-focus]
+herdr pane swap --direction left|right|up|down [--pane ID|--current]
+herdr pane swap --source-pane ID --target-pane ID
+herdr pane move <pane_id> --tab <tab_id> --split right|down [--target-pane ID] [--ratio FLOAT] [--focus|--no-focus]
+herdr pane move <pane_id> --new-tab [--workspace ID] [--label TEXT] [--focus|--no-focus]
+herdr pane move <pane_id> --new-workspace [--label TEXT] [--tab-label TEXT] [--focus|--no-focus]
+herdr pane close <pane_id>
+```
+
+读取输出:
+
+```bash
+herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N]
+herdr pane read <pane_id> --source visible --ansi
+herdr pane read <pane_id> --source recent-unwrapped --lines 120
+```
+
+发送输入:
+
+```bash
+herdr pane send-text <pane_id> <text>
+herdr pane send-keys <pane_id> <key> [key ...]
+herdr pane run <pane_id> <command>
+```
+
+`<key>` 使用 Herdr 的组合键语法: `a` 这类普通可打印键,`enter`、`tab`、`esc`、`backspace`、`left`、`right`、`up`、`down` 这类特殊键,`ctrl+h`、`control+j`、`alt+x`、`shift+tab` 这类修饰组合键,`f1` 这类功能键,以及 `minus`、`plus`、`backtick` 这类命名标点。旧式的 `C-c` 和 `c-c` 作为 `ctrl+c` 的别名被接受。
+
+`pane run` 把文本和回车作为一个原子操作提交。发送命令时优先用它,而不是 `send-text` 加 `send-keys Enter`。
+
+从自定义钩子上报智能体状态:
+
+```bash
+herdr pane report-agent <pane_id> \
+ --source ID \
+ --agent LABEL \
+ --state idle|working|blocked|unknown \
+ [--message TEXT] \
+ [--custom-status TEXT] \
+ [--seq N] \
+ [--agent-session-id ID] \
+ [--agent-session-path PATH]
+```
+
+当官方集成上报了原生会话引用时,`pane get`、`pane list`、`agent get` 和 `agent list` 会包含一个只读的 `agent_session` 对象。没有存储原生会话引用时,该字段被省略。
+
+当 Herdr 能解析控制窗格的前台进程的 cwd 时,这些命令会包含 `foreground_cwd`。已有的 `cwd` 字段仍然是用于标签和 follow-cwd 行为的窗格/工作区 cwd。
+
+上报仅用于展示的窗格元数据,而不接管语义状态:
+
+```bash
+herdr pane report-metadata <pane_id> \
+ --source ID \
+ [--agent LABEL] \
+ [--applies-to-source ID] \
+ [--title TEXT|--clear-title] \
+ [--display-agent TEXT|--clear-display-agent] \
+ [--custom-status TEXT|--clear-custom-status] \
+ [--state-label STATUS=TEXT] \
+ [--clear-state-labels] \
+ [--seq N] \
+ [--ttl-ms N]
+```
+
+`STATUS` 是 `idle`、`working`、`blocked`、`done` 或 `unknown` 之一。`--agent` 是对权威智能体标签的守卫。`--applies-to-source` 是对活动生命周期权威来源的守卫。用 `--display-agent` 修改可见名称。
+
+元数据文本在存储前会被规范化。Herdr 去掉首尾空白、移除控制字符、把 `--custom-status` 截断到 32 个字符,把 `--title`、`--display-agent` 和每个 `--state-label` 的值截断到 80 个字符。规范化后为空的值被忽略。
+
+`--source` 和 `--applies-to-source` 必须不超过 80 个字符,并且只能包含 ASCII 字母、数字、冒号、点、下划线和连字符。`--ttl-ms` 让元数据自动过期,取值必须在 `1` 到 `86400000` 毫秒之间。想让元数据一直保留到被替换、清除或窗格关闭时,省略它。`--seq` 让 Herdr 忽略来自同一 `--source` 的过期上报;过期上报会被 API 接受,但被窗格状态忽略。
+
+## 智能体
+
+```bash
+herdr agent list
+herdr agent get <target>
+herdr agent read <target> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi]
+herdr agent send <target> <text>
+herdr agent rename <target> <name>|--clear
+herdr agent focus <target>
+herdr agent wait <target> --status <idle|working|blocked|unknown> [--timeout MS]
+herdr agent attach <target> [--takeover]
+herdr agent start <name> [--cwd PATH] [--workspace ID] [--tab ID] [--split right|down] [--env KEY=VALUE] [--focus|--no-focus] -- <argv...>
+herdr agent explain <target> [--json|--verbose]
+herdr agent explain --file PATH --agent LABEL [--json|--verbose]
+```
+
+智能体目标可以是终端 ID、唯一的智能体名称、检测到或上报的智能体标签,以及旧式窗格 ID。名称和标签是智能体的身份。终端 ID 和旧式窗格 ID 是底层的逃生舱。
+
+`agent read` 读取解析出的终端流。`agent send` 向该流写入字面文本。`agent get`、`agent focus`、`agent wait` 和 `agent attach` 要求解析出的终端具有智能体身份。`agent rename` 可以赋予这个身份。
+
+`agent explain` 请求运行中的服务器对屏幕检测所用的同一份底部缓冲区检测快照进行分类,因此实时输出反映服务器生效的清单缓存。因为它使用 `agent.explain` socket 方法,升级 Herdr 后,请先重启或交接到更新后的服务器,再使用实时 explain。用 `--file PATH --agent LABEL` 可以改为在本地解释一份保存的样本。默认输出显示智能体、最终状态、清单来源和版本、匹配的规则及其区域证据,以及任何回退、跳过或警告原因。加 `--verbose` 可以看到可见证据标志、缓存的远程版本、本地覆盖的遮蔽情况、远程更新状态,以及带匹配器和区域证据的完整已评估规则列表。提交问题报告或写测试时加 `--json`。
+
+普通终端、服务器、测试、shell 或底层终端控制,请使用 `pane send-text`、`pane send-keys`、`pane run` 和 `terminal attach`。想带回车提交命令时用 `pane run`。
+
+## 直接终端附加
+
+```bash
+herdr terminal attach <terminal_id> [--takeover]
+herdr terminal title set <title>
+herdr terminal title clear
+```
+
+从直接附加中用 `ctrl+b q` 分离。用 `ctrl+b ctrl+b` 发送字面的 `ctrl+b`。
+`terminal title clear` 恢复 Herdr 默认的外层终端窗口标题。
+
+## 等待
+
+等待窗格中的输出:
+
+```bash
+herdr wait output <pane_id> --match <text> [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--regex] [--raw]
+```
+
+等待窗格的智能体状态:
+
+```bash
+herdr wait agent-status <pane_id> --status <idle|working|blocked|done|unknown> [--timeout MS]
+```
+
+普通命令和服务器用 `wait output`。编程智能体用 `wait agent-status`。
+
+## 集成
+
+```bash
+herdr integration install pi
+herdr integration install omp
+herdr integration install claude
+herdr integration install codex
+herdr integration install copilot
+herdr integration install devin
+herdr integration install droid
+herdr integration install kimi
+herdr integration install opencode
+herdr integration install kilo
+herdr integration install hermes
+herdr integration install qodercli
+herdr integration install cursor
+herdr integration uninstall pi
+herdr integration uninstall omp
+herdr integration uninstall claude
+herdr integration uninstall codex
+herdr integration uninstall copilot
+herdr integration uninstall devin
+herdr integration uninstall droid
+herdr integration uninstall kimi
+herdr integration uninstall opencode
+herdr integration uninstall kilo
+herdr integration uninstall hermes
+herdr integration uninstall qodercli
+herdr integration uninstall cursor
+herdr integration status [--outdated-only]
+```
+
+## 插件
+
+插件命令用于安装和运行本地可执行的工作流插件。插件是清单加进程外命令;Herdr 负责宿主侧,插件负责自己的实现语言。
+
+安装、列出和移除插件:
+
+```bash
+herdr plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]
+herdr plugin list [--plugin ID] [--json]
+herdr plugin uninstall <plugin_id|owner/repo[/subdir...]>
+herdr plugin enable <plugin_id>
+herdr plugin disable <plugin_id>
+```
+
+`plugin install` 只接受 GitHub 简写,比如 `ogulcancelik/herdr-plugin-examples/worktree-bootstrap`。它使用 `git`,在交互式终端显示信任预览,运行受支持的清单构建命令,并把 GitHub 安装保存在 Herdr 管理的目录中。非交互式安装用 `--yes`。重新安装 GitHub 管理的插件会替换该托管检出。不允许覆盖安装到本地链接的插件之上。插件清单必须声明 `min_herdr_version`;当插件要求更新的 Herdr 二进制时,install 和 link 会失败。`plugin list` 默认是人类可读的;要原始 API 响应就传 `--json`。
+
+本地开发:
+
+```bash
+herdr plugin link <path> [--disabled]
+herdr plugin unlink <plugin_id>
+```
+
+`plugin link` 接受包含 `herdr-plugin.toml` 的插件目录,或直接指向清单的路径。从本地检出编写或测试插件时,它仍然是正确的命令。`plugin unlink` 注销插件、不动文件。`plugin uninstall` 注销插件,并同时删除 Herdr 管理的 GitHub 检出文件。对 GitHub 安装,uninstall 既接受插件 id,也接受与 install 相同的 `owner/repo[/subdir...]` 简写。动作、事件钩子、窗格和链接处理器在清单中声明;运行时动作注册不在 v1 范围内。
+
+配置目录:
+
+```bash
+herdr plugin config-dir <plugin_id>
+```
+
+`plugin config-dir` 打印插件的配置目录,需要时会创建它 (旧版插件配置位置存在时会从那里初始化)。在安装文档和 shell 脚本中用它给用户指出一个稳定路径,用于存放 `.env` 等用户可编辑配置,与托管的插件检出分开。
+
+动作:
+
+```bash
+herdr plugin action list [--plugin ID]
+herdr plugin action invoke <action_id> [--plugin ID]
+```
+
+`plugin action invoke` 为一个已安装、已启用、平台兼容的插件动作启动清单命令,并在 JSON 响应中打印已启动命令的日志记录。当多个插件使用相同的动作 id 时,使用限定的动作 id (`plugin.id.action`)。本地动作 id 不能包含点,所以即使插件 id 包含点,限定 id 也不会有歧义。
+
+日志:
+
+```bash
+herdr plugin log list [--plugin ID] [--limit N]
+```
+
+托管终端窗格:
+
+```bash
+herdr plugin pane open --plugin ID --entrypoint ID [--placement overlay|split|tab|zoomed] [--workspace ID] [--target-pane PANE] [--direction right|down] [--cwd PATH] [--env KEY=VALUE] [--focus|--no-focus]
+herdr plugin pane focus <pane_id>
+herdr plugin pane close <pane_id>
+```
+
+`plugin pane open` 要求插件已链接、已启用并与当前平台兼容。它把清单声明的 `[[panes]]` 命令作为 Herdr 管理的终端窗格启动。清单的默认值是 `overlay`,在活动窗格上方打开一个临时的缩放覆盖层。它也可以作为分割、新标签页或缩放窗格打开。非终端的原生插件窗格是之后的能力面。
+
+`--env KEY=VALUE` 可以在启动进程的命令上重复使用,只作用于新启动的进程。当与调用方提供的环境变量冲突时,`HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ENV`、`HERDR_WORKSPACE_ID`、`HERDR_TAB_ID`、`HERDR_PANE_ID`、`HERDR_PLUGIN_ID`、`HERDR_PLUGIN_ROOT`、`HERDR_PLUGIN_CONFIG_DIR`、`HERDR_PLUGIN_STATE_DIR`、`HERDR_PLUGIN_ENTRYPOINT_ID` 和 `HERDR_PLUGIN_CONTEXT_JSON` 等 Herdr 管理的变量保持权威。
+
+## 读取来源
+
+| 来源 | 含义 |
+| --- | --- |
+| `visible` | 当前渲染的屏幕。最适合 UI 反馈循环。 |
+| `recent` | 带终端折行的最近回滚内容。 |
+| `recent-unwrapped` | 不带软折行的最近回滚内容。最适合日志。 |
+| `detection` | 智能体屏幕检测使用的底部缓冲区快照。 |
+
+## 环境变量
+
+| 变量 | 用途 |
+| --- | --- |
+| `HERDR_CONFIG_PATH` | 覆盖配置文件路径。 |
+| `HERDR_SESSION` | 为 CLI 命令选择命名会话。 |
+| `HERDR_SOCKET_PATH` | 底层 socket 路径覆盖。 |
+| `HERDR_ENV` | 在 Herdr 管理的窗格进程内设为 `1`。 |
+| `HERDR_PANE_ID` | 运行中窗格进程的公开窗格 id。 |
+| `HERDR_TAB_ID` | 运行中窗格进程的公开标签页 id。 |
+| `HERDR_WORKSPACE_ID` | 运行中窗格进程的公开工作区 id。 |
+| `HERDR_LOG` | 设置日志过滤,例如 `HERDR_LOG=herdr=debug`。 |
+| `HERDR_DISABLE_SOUND` | 即使启用了声音通知也禁用声音播放。 |
diff --git a/website/src/content/docs/zh-cn/concepts.mdx b/website/src/content/docs/zh-cn/concepts.mdx
new file mode 100644
index 00000000..ab950416
--- /dev/null
+++ b/website/src/content/docs/zh-cn/concepts.mdx
@@ -0,0 +1,85 @@
+---
+title: 核心概念
+description: 理解 Herdr 的工作区、标签页、窗格、智能体、会话和模式。
+---
+
+Herdr 是一个终端工作区管理器。它让真实的终端进程持续运行,并在其之上添加结构。
+
+## 工作区
+
+工作区是最顶层的项目容器。为每个仓库、任务或调查使用一个工作区。
+
+工作区拥有标签页和窗格。它在侧边栏中的状态由内部的智能体汇总而来,让你一眼看出哪个项目需要关注。
+
+## 标签页
+
+标签页是工作区内的一种布局。用标签页来分隔不同视图,比如 `agents`、`logs`、`server` 或 `review`。
+
+标签页可以通过 CLI 和 socket API 寻址。
+
+## 窗格
+
+窗格是一个真实的终端。Herdr 渲染终端输出,把输入传回进程,并在客户端分离后保留窗格。
+
+窗格可以向右或向下分割。它们可以手动重命名、通过 CLI 读取、接收输入,以及被关闭。
+
+## 鼠标 UI
+
+Herdr 是鼠标原生的。你可以点击窗格、标签页、工作区和智能体,可以拖动分割边框、选择文本、使用右键菜单。下文的所有操作都可以用鼠标完成;按键绑定是可选的一层。
+
+如果你偏好纯键盘操作,或者不想让 Herdr 捕获鼠标输入,可以禁用鼠标捕获:
+
+```toml
+[ui]
+mouse_capture = false
+```
+
+## 智能体
+
+智能体是 Herdr 在窗格内识别出的进程。Herdr 通过前台进程、屏幕清单和可选的集成来检测智能体。
+
+智能体状态如下:
+
+| 状态 | 含义 |
+| --- | --- |
+| `blocked` | 智能体需要输入、审批或决策。 |
+| `working` | 智能体正在运行。 |
+| `done` | 智能体已完成,你还没有查看。 |
+| `idle` | 智能体已完成或在等待,并且已被查看过。 |
+| `unknown` | Herdr 无法有把握地判断状态。 |
+
+## 会话
+
+会话是一个持久的 Herdr 服务器命名空间。默认的 `herdr` 命令连接到默认会话。
+
+命名会话是彼此独立的运行时命名空间:
+
+```bash
+herdr session list
+herdr session attach work
+herdr session attach side-project
+```
+
+优先使用工作区。当你需要完全独立的窗格、socket 和持久化运行时状态时,才使用命名会话。
+
+## 客户端与服务器
+
+默认情况下,Herdr 以一个后台服务器加一个或多个已连接客户端的方式运行。
+
+服务器拥有窗格和进程状态。客户端是连接到该服务器的终端 UI。
+
+用 `ctrl+b q` 分离客户端。服务器和智能体会继续运行。
+
+如果想结束会话并停止其中的窗格,停止服务器:
+
+```bash
+herdr server stop
+```
+
+## 模式
+
+Herdr 有终端模式、前缀模式和导航模式。
+
+终端模式把按键发送给聚焦的窗格。前缀模式在按下前缀键后等待一个 Herdr 动作。导航模式是常驻的工作区导航界面。
+
+按下前缀键 (默认 `ctrl+b`),再按一个动作键,比如 `c` 新建标签页,`w` 打开工作区导航。第一次接触前缀键的概念?参见[键盘](/zh-cn/docs/keyboard/)。
diff --git a/website/src/content/docs/zh-cn/configuration.mdx b/website/src/content/docs/zh-cn/configuration.mdx
new file mode 100644
index 00000000..e6bccd81
--- /dev/null
+++ b/website/src/content/docs/zh-cn/configuration.mdx
@@ -0,0 +1,526 @@
+---
+title: 配置
+description: 配置 Herdr 的按键绑定、主题、侧边栏行为、通知和高级选项。
+---
+
+Herdr 无需配置文件即可工作。当你想要自定义按键、主题、侧边栏设置、通知或高级行为时再添加。
+
+## 配置文件
+
+Herdr 从这里读取配置:
+
+```text
+~/.config/herdr/config.toml
+```
+
+打印完整的默认配置:
+
+```bash
+herdr --default-config
+```
+
+想要一个完整的起点,可以把它保存为你的配置:
+
+```bash
+herdr --default-config > ~/.config/herdr/config.toml
+```
+
+如果某个配置值无效,Herdr 会回退到安全默认值,并在启动时显示警告。
+
+当 `onboarding` 缺失或为 true 时,Herdr 会显示首次运行引导。从引导继续会写入 `onboarding = false` 并打开设置的集成标签页。安装完成后想跳过该流程时可以设置它。
+
+```toml
+onboarding = false
+```
+
+## 更新
+
+Linux 和 macOS 的直接安装默认使用稳定更新通道。Windows 测试版安装默认使用预览通道,在稳定的 Windows 发布可用之前不能切换到稳定版。
+
+```toml
+[update]
+channel = "stable"
+version_check = true
+manifest_check = true
+```
+
+设置 `channel = "preview"` 让 `herdr update` 安装从当前开发分支手动发布的预览构建。Homebrew、mise 和 Nix 安装忽略预览通道,通过各自的包管理器更新。
+
+设置 `version_check = false` 禁用对新 Herdr 版本的后台检查。手动 `herdr update` 仍使用配置的通道。
+
+设置 `manifest_check = false` 禁用后台的远程智能体检测清单检查。Herdr 仍使用内置清单和本地覆盖。
+
+## 重载配置
+
+编辑 `config.toml` 后重载运行中的服务器:
+
+```bash
+herdr server reload-config
+```
+
+也可以在 Herdr 中打开全局菜单并选择 `reload config`。
+
+重载会在不重启窗格的情况下应用大多数 UI 设置。仅启动时生效的设置仍需要重启。
+
+## 终端默认值
+
+设置 Herdr 为新建交互式窗格使用的可执行文件:
+
+```toml
+[terminal]
+default_shell = "nu"
+```
+
+未设置或为空时,Herdr 使用 `$SHELL`,然后是 `/bin/sh`。这是可执行文件名或路径,不是 shell 命令行。现有窗格在重建之前保持当前 shell。命令窗格仍通过 `/bin/sh -c` 运行;分离式自定义命令按键绑定使用 Herdr 已有的 `/bin/sh -lc` 路径。
+
+设置 Herdr 如何启动新建交互式窗格的 shell:
+
+```toml
+[terminal]
+shell_mode = "auto"
+```
+
+`shell_mode = "auto"` 在 macOS 上启动登录 shell,使 `/usr/libexec/path_helper` 这类仅登录时的 PATH 设置和 Homebrew shell 初始化能在新窗格中运行。在其他平台上,它保持现有的非登录 shell 行为。用 `"login"` 强制登录 shell 启动,用 `"non_login"` 选择退出。命令窗格、分离式自定义命令按键绑定和显式 argv 启动保持已有的命令执行路径。
+
+设置新窗格、标签页和工作区的工作目录策略:
+
+```toml
+[terminal]
+new_cwd = "follow"
+```
+
+`new_cwd = "follow"` 保持默认行为,继承来源窗格或工作区。没有来源工作区时,Herdr 从 `$HOME` 启动。用 `"home"` 总是从 `$HOME` 启动,用 `"current"` 使用 Herdr 的进程目录,或者用 `"~/Projects"` 这类固定路径。来自 CLI 或 socket API 的显式 `--cwd` 值仍然优先。
+
+## Worktree
+
+设置从侧边栏创建 Git worktree 检出时 Herdr 使用的根目录:
+
+```toml
+[worktrees]
+directory = "~/.herdr/worktrees"
+```
+
+Herdr 在 `<directory>/<repo>/<branch-slug>` 下创建检出。想要同级目录风格的检出,把它设为 `~/Projects/herdr-worktrees` 这类目录。相对值会在应用配置时解析为绝对路径。
+
+worktree 操作在 Git 工作区行上可用。`New worktree` 创建一个检出,输入的分支已存在时检出该本地分支,否则创建分支,作为新 Herdr 工作区打开,并归组到来源工作区之下。`Open worktree...` 列出该仓库已有的 Git worktree 检出;选择已打开的检出会聚焦它,选择已关闭的检出会在同一组中打开它。
+
+归组的 worktree 仍然像普通 Herdr 工作区一样: 可以聚焦、重命名、关闭,并拥有自己的标签页和窗格。父行是原始工作区。关闭父行会关闭整个 Herdr 组,但不会删除检出文件夹或分支。
+
+删除 worktree 检出是显式操作。在归组的子工作区上使用 `Delete worktree checkout...` 运行 `git worktree remove`。Herdr 先请求 Git 安全删除。如果 Git 因为检出有修改或未跟踪文件而拒绝,Herdr 会在执行强制删除前再次询问。分支不会被删除。
+
+## 远程连接
+
+远程连接默认用带临时保活兜底的方式管理它的 SSH 桥。
+
+```toml
+[remote]
+manage_ssh_config = true
+```
+
+启用时,`herdr --remote` 写入一个私有的临时 SSH 配置: 先包含你的 `~/.ssh/config` 和 `/etc/ssh/ssh_config`,再添加兜底的 `ServerAliveInterval` 和 `ServerAliveCountMax` 值。你自己的 SSH 保活设置优先。设置 `manage_ssh_config = false` 用普通 `ssh` 运行桥接,不使用 Herdr 生成的配置。
+
+## 按键绑定
+
+前缀键的入门介绍和经过验证的免前缀配置,见[键盘](/zh-cn/docs/keyboard/)。
+
+Herdr 有类似 tmux 的前缀模式。默认前缀是 `ctrl+b`。按键绑定字符串是显式的: `prefix+n` 表示先按配置的前缀再按 `n`;`ctrl+alt+n` 是终端模式的直接快捷键。
+
+一个小型的按键绑定覆盖长这样:
+
+```toml
+[keys]
+prefix = "ctrl+b"
+goto = "prefix+g"
+new_tab = "prefix+c"
+next_tab = "prefix+n"
+previous_tab = "prefix+p"
+focus_pane_left = "prefix+h"
+navigate_workspace_down = "j"
+navigate_pane_down = "ctrl+j"
+split_horizontal = "prefix+minus"
+```
+
+默认键位以前缀为先,避免会从 shell、编辑器、tmux 或终端应用抢输入的直接快捷键。常见默认值包括:
+
+```toml
+[keys]
+detach = "prefix+q"
+workspace_picker = "prefix+w"
+goto = "prefix+g"
+new_workspace = "prefix+shift+n"
+new_worktree = "prefix+shift+g"
+rename_workspace = "prefix+shift+w"
+close_workspace = "prefix+shift+d"
+navigate_workspace_up = "up"
+navigate_workspace_down = "down"
+navigate_pane_left = "h"
+navigate_pane_down = "j"
+navigate_pane_up = "k"
+navigate_pane_right = "l"
+remote_image_paste = "ctrl+v"
+new_tab = "prefix+c"
+previous_tab = "prefix+p"
+next_tab = "prefix+n"
+switch_tab = "prefix+1..9"
+rename_tab = "prefix+shift+t"
+close_tab = "prefix+shift+x"
+copy_mode = "prefix+["
+focus_pane_left = "prefix+h"
+focus_pane_down = "prefix+j"
+focus_pane_up = "prefix+k"
+focus_pane_right = "prefix+l"
+swap_pane_left = "prefix+shift+h"
+swap_pane_down = "prefix+shift+j"
+swap_pane_up = "prefix+shift+k"
+swap_pane_right = "prefix+shift+l"
+cycle_pane_next = "prefix+tab"
+cycle_pane_previous = "prefix+shift+tab"
+last_pane = ""
+split_vertical = "prefix+v"
+split_horizontal = "prefix+minus"
+close_pane = "prefix+x"
+zoom = "prefix+z"
+resize_mode = "prefix+r"
+toggle_sidebar = "prefix+b"
+```
+
+可选动作默认未设置。用 `prefix+` 绑定它们获得前缀模式行为,或者在有意想要直接快捷键时用显式的修饰组合键:
+
+```toml
+[keys]
+previous_workspace = "prefix+shift+left"
+next_workspace = "prefix+shift+right"
+last_pane = "prefix+tab"
+open_worktree = "prefix+shift+o"
+remove_worktree = "prefix+alt+d"
+next_tab = ["prefix+n", "ctrl+alt+]"]
+```
+
+`last_pane` 跨工作区和标签页切回上一个聚焦的窗格。它默认未设置,因为 tmux 风格的窗格绑定 `prefix+l` 已被用于向右聚焦窗格。
+
+`remote_image_paste` 只在 `herdr --remote` 中生效。它是本地客户端的快捷键,把本地剪贴板图像发送到远程窗格。设为空字符串可禁用这个原始按键快捷键;外层终端发送的 paste-image 信号仍然有效。
+
+按键字符串接受普通按键、`ctrl+a`、`shift+n`、`alt+1`、`cmd+k` 这类修饰组合,以及 `enter`、`tab`、`esc`、`left`、`right`、`up`、`down` 这类特殊键。也接受 `minus`、`comma`、`ampersand`、`plus`、`backtick` 这类命名标点。像 `n` 这样的普通可打印键直接绑定是不安全的,因为它会拦截打字;除非有意要直接绑定,否则用 `prefix+n`。`navigate_workspace_*` 和 `navigate_pane_*` 字段仅在导航模式下生效,可以用 `j`、`k` 这类普通键;它们不能使用 `prefix+`、`esc`、`enter`、`tab`、`shift+tab`、`left`、`right` 或无修饰的 `1` 到 `9`。左右方向键是窗格左/右导航的永久别名。这些导航模式快捷键与 `focus_pane_down = "prefix+j"` 这类通用动作绑定相互独立;两者使用同一个键时,导航模式打开期间导航模式的快捷键优先。Alt、Cmd/Super 和带修饰键的标点取决于你的终端和 tmux 设置。
+
+如果你有旧的自定义按键绑定并想要新的默认值,运行 `herdr config reset-keys`。Herdr 会备份 `config.toml`,移除 `[keys]` 和 `[[keys.command]]`,并在重启或 `herdr server reload-config` 后使用内置的 v2 默认值。
+
+## 索引跳转
+
+索引式按键绑定在普通按键绑定字段中使用 `1..9`:
+
+```toml
+[keys]
+switch_tab = "prefix+1..9"
+switch_workspace = "prefix+shift+1..9"
+focus_agent = "prefix+alt+1..9"
+```
+
+旧式的 `[keys.indexed]` 表出于兼容仍会被解析,但新配置应优先使用显式的动作字段。
+
+## 自定义命令按键绑定
+
+自定义命令使用同样的按键绑定语法。
+
+```toml
+[[keys.command]]
+key = "prefix+alt+g"
+type = "pane"
+command = "lazygit"
+description = "run lazygit"
+```
+
+`type = "pane"` 打开一个临时窗格,并在命令退出时关闭它。
+
+`type = "shell"` 在后台分离运行。
+
+`type = "plugin_action"` 调用已安装插件的动作 id。动作 id 不全局唯一时使用限定 id:
+
+```toml
+[[keys.command]]
+key = "prefix+l"
+type = "plugin_action"
+command = "example.layout.apply"
+description = "apply layout"
+```
+
+可以提供可选的 `description`。指定后,它会显示在按键帮助面板 (`prefix+?` 打开) 中,替代默认的 `'custom command'` 标签。
+
+自定义命令在可用时会收到 `HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ACTIVE_WORKSPACE_ID`、`HERDR_ACTIVE_TAB_ID`、`HERDR_ACTIVE_PANE_ID` 和 `HERDR_ACTIVE_PANE_CWD`。当 Herdr 能检测到时,shell 命令会从聚焦窗格的工作目录运行。
+
+## 主题
+
+选择内置主题:
+
+```toml
+[theme]
+name = "catppuccin"
+```
+
+内置主题:
+
+`catppuccin`、`catppuccin-latte`、`terminal`、`tokyo-night`、`tokyo-night-day`、`dracula`、`nord`、`gruvbox`、`gruvbox-light`、`one-dark`、`one-light`、`solarized`、`solarized-light`、`kanagawa`、`kanagawa-lotus`、`rose-pine`、`rose-pine-dawn`、`vesper`。
+
+想让 Herdr 的 UI 颜色跟随宿主终端的 ANSI 调色板时用 `terminal`。
+
+要让 Herdr 在宿主终端报告明暗外观变化时自动切换自己的 UI 主题,启用主题自动切换:
+
+```toml
+[theme]
+name = "catppuccin"
+auto_switch = true
+light_name = "catppuccin-latte"
+dark_name = "catppuccin"
+```
+
+`auto_switch` 默认为 `false`,所以现有主题配置保持手动行为。省略 `light_name` 或 `dark_name` 时,如果配置的 `name` 存在对应的内置姊妹主题,Herdr 就使用它,比如 `tokyo-night`/`tokyo-night-day` 或 `gruvbox`/`gruvbox-light`。在设置中手动选择主题会禁用 `auto_switch`。
+
+你可以覆盖单个颜色:
+
+```toml
+[theme.custom]
+panel_bg = "reset"
+accent = "#a6e3a1"
+green = "#a6e3a1"
+blue = "#89b4fa"
+red = "#f38ba8"
+yellow = "#f9e2af"
+```
+
+颜色值接受十六进制、命名颜色、`rgb(r,g,b)`,或 `reset`、`default`、`none`、`transparent` 这类重置别名。
+
+## UI 与侧边栏
+
+侧边栏是 Herdr 的主仪表盘。它显示工作区、标签页、窗格和智能体状态。
+
+常用选项:
+
+```toml
+[ui]
+sidebar_width = 32
+sidebar_min_width = 18
+sidebar_max_width = 36
+mobile_width_threshold = 64
+mouse_capture = true
+right_click_passthrough_modifier = ""
+redraw_on_focus_gained = true
+mouse_scroll_lines = 3
+confirm_close = true
+prompt_new_tab_name = true
+pane_borders = true
+pane_gaps = true
+show_agent_labels_on_pane_borders = false
+agent_panel_sort = "spaces"
+accent = "cyan"
+```
+
+`sidebar_min_width` 和 `sidebar_max_width` 以列数控制展开侧边栏的调整范围。默认是 18 和 36。
+
+`mobile_width_threshold` 控制 Herdr 使用移动端单列布局的终端宽度阈值。默认 64 列;折叠屏、平板或宽屏手机终端可以调大。
+
+智能体面板显示所有空间中的所有智能体。`agent_panel_sort` 可以是 `spaces` 或 `priority`;`workspaces` 作为 `spaces` 的别名被接受。默认是 `spaces`,让智能体按空间顺序分组。`priority` 按关注优先级排序: blocked、done、working、idle,然后是 unknown。同一状态内,最近改变状态的智能体排在前面。
+
+`confirm_close` 控制关闭工作区时是否需要确认。`prompt_new_tab_name` 控制新标签页是否先询问名称。
+
+如果想让终端处理普通点击,比如 command+点击 URL,设置 `mouse_capture = false`。鼠标捕获启用时,如果终端把带修饰键的点击传给 Herdr,Ctrl+点击可以打开窗格链接。macOS 也是如此;Herdr 捕获鼠标输入期间,Cmd+点击不会与普通点击区分上报。终端原生的绕过路径: Linux 上用 Shift+Ctrl+点击,macOS 上用 Shift+Cmd+点击。
+
+如果想让 Ctrl+右键点击、按住和拖动手势到达启用鼠标上报的窗格应用,而不是打开 Herdr 的窗格菜单,设置 `right_click_passthrough_modifier = "ctrl"`。默认为空,即禁用这种透传。支持的修饰键有 `ctrl`、`alt`、`cmd`、`super`、`meta` 和 `hyper`;`shift` 被拒绝,因为许多终端把 Shift+鼠标保留给它们自己的鼠标绕过。
+
+设置 `redraw_on_focus_gained = false` 可以避免切回 Herdr 时可见的全屏刷新。默认为 `true`,因为完整重绘能从罕见的过期或脏的宿主终端画面中恢复。
+
+设置 `mouse_scroll_lines` 改变鼠标滚轮每格滚动的窗格回滚行数。默认是 3。请求鼠标上报的窗格应用仍然直接接收滚轮事件。备用屏幕应用没有可滚动的回滚内容;参见[回滚缓冲区](#回滚缓冲区)。
+
+设置 `pane_borders = false` 移除分割窗格边框。设置 `pane_gaps = false` 让分割窗格共用紧凑的分隔线。禁用边框时,窗格间距是窗格之间一个空白终端单元格。终端单元格通常高大于宽,所以上下窗格之间一行的间距可能看起来比左右窗格之间一列的间距更大。
+
+如果想在没有手动窗格标签时,把检测到的智能体标签显示在分割窗格边框上,设置 `show_agent_labels_on_pane_borders = true`。
+
+## 通知
+
+Herdr 可以在智能体完成或需要输入时显示弹出通知。
+
+```toml
+[ui.toast]
+delivery = "off"
+delay_seconds = 1
+
+[ui.toast.herdr]
+position = "bottom-right"
+
+[ui.toast.clipboard]
+enabled = true
+position = "bottom-center"
+```
+
+`delivery = "off"` 禁用弹出通知。这是默认值。
+
+`delivery = "herdr"` 在 Herdr UI 内显示 toast。点击 toast,或绑定 `keys.open_notification_target`,可以聚焦目标工作区、标签页和窗格。`ui.toast.herdr.position` 可设为 `top-left`、`top-right`、`bottom-left` 或 `bottom-right`;桌面位置相对于完整的 Herdr 画面。
+
+`delivery = "terminal"` 请求外层终端显示桌面通知。Herdr 为 Ghostty、iTerm2、Kitty 和 WezTerm 发送终端通知转义序列。在 SSH 上很有用,因为通知归本地终端所有。
+
+`delivery = "system"` 直接请求本地操作系统。在 macOS 上,Herdr 优先使用 `terminal-notifier`,不可用时回退到 `/usr/bin/osascript`。`terminal-notifier` 可以在你点击通知时激活承载的终端。在 Linux 上,Herdr 使用 `notify-send`,并要求 `DISPLAY` 或 `WAYLAND_DISPLAY`。
+
+弹出通知用于后台提醒。Herdr 对活动标签页抑制弹出。
+
+`delay_seconds` 在发送完成或需要输入的智能体通知前等待。只有在延迟结束时窗格仍处于相同状态,Herdr 才会通知。设为 `0` 立即通知。有效值为 `0` 到 `3600`。
+
+剪贴板反馈单独配置,因为它确认的是前台复制操作,并且从不通过 terminal 或 system 投递。设置 `ui.toast.clipboard.enabled = false` 隐藏“已复制到剪贴板”弹窗。剪贴板位置有 `top-left`、`top-center`、`top-right`、`bottom-left`、`bottom-center` 和 `bottom-right`。
+
+## 声音
+
+声音通知默认启用,由本地 Herdr 客户端播放。
+
+```toml
+[ui.sound]
+enabled = true
+```
+
+Herdr 在智能体完成时播放完成音,在智能体需要输入时播放提醒音。在共享机器或远程服务器上,除非明确想要声音,否则设置 `enabled = false`。
+
+在 macOS 上,Herdr 使用 `afplay`。在 Linux 上,Herdr 按顺序尝试支持 mp3 的播放器: `paplay`、`pw-play`、`ffplay`、`mpg123`,然后是 `mpv`。没有可用播放器时,声音播放被跳过,Herdr 记录一条警告。
+
+自定义声音必须是 mp3 文件。相对路径从配置文件所在目录解析。
+
+```toml
+[ui.sound]
+path = "sounds/notification.mp3"
+done_path = "sounds/done.mp3"
+request_path = "sounds/request.mp3"
+```
+
+`path` 为所有声音通知设置一个声音。`done_path` 和 `request_path` 只覆盖完成音和需要输入音。
+
+按智能体的声音覆盖接受 `default`、`on` 或 `off`。用检测到的智能体标签做键,比如 `claude`、`codex`、`devin` 或 `droid`。Droid 默认静音。
+
+```toml
+[ui.sound.agents]
+droid = "off"
+claude = "on"
+```
+
+## 回滚缓冲区
+
+设置新建窗格的回滚缓冲区大小:
+
+```toml
+[advanced]
+scrollback_limit_bytes = 10485760
+```
+
+现有窗格在重建之前保持当前缓冲区。
+
+只有应用写入主屏幕时,窗格才显示滚动条。切换到备用屏幕的全屏应用 (vim、htop、设置了 `CLAUDE_CODE_NO_FLICKER=1` 的 Claude Code) 不产生回滚内容,因此不出现滚动条,滚轮事件转而路由给应用。请用应用自己的按键或 UI 滚动。
+
+## 窗格屏幕历史
+
+默认情况下,完整的会话重启会恢复工作区、标签页、窗格、cwd、布局和焦点,但不保存窗格内容。
+
+窗格屏幕历史默认关闭。窗格输出可能包含密钥、令牌、提示词和命令输出,所以只在你确实想让 Herdr 跨完整服务器重启保存最近窗格内容时才开启:
+
+```toml
+[experimental]
+pane_history = true
+```
+
+也可以在 Settings > Experiments > pane screen history 中切换。
+
+开启后,Herdr 把保存的窗格历史存放在 `session.json` 旁边的 `session-history.json` 中。
+
+窗格屏幕历史与实时持久化、快照恢复、智能体原生会话恢复和实时交接的区别,见[会话状态与恢复](/zh-cn/docs/session-state/)。
+
+## 嵌套启动
+
+Herdr 通常会阻止你在 Herdr 内启动 Herdr。
+
+```toml
+[experimental]
+allow_nested = false
+```
+
+仅在测试时启用嵌套启动。
+
+## Kitty graphics
+
+Kitty graphics 支持是实验性的。
+
+```toml
+[experimental]
+kitty_graphics = false
+```
+
+除非你在测试终端图像行为,否则保持关闭。
+
+## 智能体会话恢复
+
+Herdr 可以在服务器重启后,让受支持的智能体窗格在其原生对话会话中重新启动。
+
+```toml
+[session]
+resume_agents_on_restore = true
+```
+
+这默认开启。Herdr 只恢复通过官方 Herdr 集成上报了原生会话引用的窗格。受支持的恢复目标是 Claude Code、Codex、Cursor Agent CLI、GitHub Copilot CLI、Droid、Kimi Code CLI、Qoder CLI、Pi、Hermes Agent、OpenCode 和 Kilo Code CLI。不受支持、缺失、无效、重复或过期的会话引用,会在保存的窗格目录中作为普通 shell 恢复。
+
+会话引用存储在本地 Herdr 会话快照中。它们不会出现在普通的窗格、智能体、状态或事件输出中。
+
+智能体原生会话恢复与窗格屏幕历史和实时交接的区别,见[会话状态与恢复](/zh-cn/docs/session-state/)。
+
+## IME 光标跟踪
+
+当聚焦窗格隐藏光标并自己绘制光标时 — 这在 Claude Code、pi、codex、Devin 这类 AI 智能体 TUI 中很常见 — macOS 原生输入法会停止跟踪候选窗口位置,因为外层终端不再报告光标。
+
+设置 `reveal_hidden_cursor_for_cjk_ime = true`,无视窗格的 `?25l` 请求,把聚焦窗格的光标锚点暴露给外层终端:
+
+```toml
+[experimental]
+reveal_hidden_cursor_for_cjk_ime = false
+cjk_ime_agents = []
+cjk_ime_cursor_shape = "steady_block"
+```
+
+启用后,光标保持在聚焦窗格上报的位置可见。如果窗格没有上报光标位置,锚点回退到窗格左上角,保证始终有稳定的输入法提示位置。
+
+`cjk_ime_agents` 是可选的允许列表。为空时,该显示适用于任何聚焦窗格。非空时,只在聚焦窗格检测到的智能体匹配列表中某个名称时才生效 — 适合只对自绘光标的 AI 智能体 TUI 启用,而不影响普通 shell。接受的名称: `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli` 和 `qoder`。未知名称被忽略;如果列表中没有有效名称,该显示不生效。
+
+`cjk_ime_cursor_shape` 控制为输入法锚点渲染的 DECSCUSR 形状。接受的值: `block`、`steady_block` (默认)、`underline`、`steady_underline`、`bar`、`steady_bar`。
+
+通过已有的 `[experimental]` 块热重载。
+
+启用的代价: 对隐藏光标但不绘制替代光标的应用 (vim 普通模式等),外层终端会多显示一个硬件光标。配合 `cjk_ime_agents` 把它限定到特定 TUI。
+
+## 前缀输入法切换
+
+在 macOS 上,当非 ASCII 输入法处于活动状态时,前缀模式命令可能很难使用,因为前缀命令仍会经过宿主输入法解释。
+
+设置 `switch_ascii_input_source_in_prefix = true`,在前缀模式激活期间把宿主输入法切换到系统的 ASCII 输入法:
+
+```toml
+[experimental]
+switch_ascii_input_source_in_prefix = false
+```
+
+启用后,Herdr 只在进入前缀模式后切换输入法,并在退出前缀模式时恢复之前的输入法。该设置仅限 macOS,在其他平台或系统输入法切换失败时不做任何事。
+
+也可以在 Settings > Experiments > switch to ascii input source in prefix (macOS) 中切换。
+
+## 环境变量
+
+| 变量 | 用途 |
+| --- | --- |
+| `HERDR_CONFIG_PATH` | 覆盖配置文件路径。 |
+| `HERDR_SESSION` | 为 CLI 命令选择命名会话。 |
+| `HERDR_SOCKET_PATH` | 底层 socket 路径覆盖。 |
+| `HERDR_LOG` | 设置日志过滤,例如 `HERDR_LOG=herdr=debug`。 |
+| `HERDR_DISABLE_SOUND` | 即使 `[ui.sound] enabled = true` 也禁用声音播放。 |
+
+## 日志
+
+诊断启动警告、集成状态或 socket API 行为时,日志很有用。
+
+常见日志文件:
+
+```text
+~/.config/herdr/herdr.log
+~/.config/herdr/herdr-client.log
+~/.config/herdr/herdr-server.log
+```
+
+日志自动轮转。报告问题时请附上当前日志和已轮转的同级文件。
diff --git a/website/src/content/docs/zh-cn/how-to-work.mdx b/website/src/content/docs/zh-cn/how-to-work.mdx
new file mode 100644
index 00000000..0df1b87f
--- /dev/null
+++ b/website/src/content/docs/zh-cn/how-to-work.mdx
@@ -0,0 +1,103 @@
+---
+title: 使用 Herdr 的工作方式
+description: 在本地、SSH 内或通过远程连接运行 Herdr。
+---
+
+在工作所在的地方运行 Herdr,从你所在的任何地方连接。
+
+Herdr 由一个后台会话服务器和一个或多个终端客户端组成。窗格在服务器中持续运行。客户端负责连接、分离和渲染会话。
+
+## 本地工作
+
+在项目目录中启动 Herdr:
+
+```bash
+herdr
+```
+
+Herdr 会自动启动或连接到本地后台会话。你不需要管理 socket。在窗格里照常运行 shell、服务器、测试和智能体。
+
+用 `ctrl+b q` 分离客户端。窗格会继续运行。
+
+之后重新连接:
+
+```bash
+herdr
+```
+
+如果想结束会话并停止其中的窗格,停止服务器:
+
+```bash
+herdr server stop
+```
+
+## 通过普通 SSH 的远程工作
+
+SSH 到有代码和凭据的机器,然后在那里运行 Herdr:
+
+```bash
+ssh you@server
+herdr
+```
+
+这和终端复用器的用法一样。你的 shell 在远程,Herdr 服务器在远程,智能体和窗格都运行在远程机器上。用 `ctrl+b q` 分离并断开连接,之后再 SSH 回去,重新运行 `herdr`。
+
+当你本来就工作在 SSH shell 里、在手机或平板的 SSH 客户端上,或者想要最简单的配置时,用这条路径。
+
+## 用手机工作
+
+你不需要 Herdr 手机应用或 Web 仪表盘。在手机上装任意一个 SSH 客户端,连到智能体所在的机器,在那里启动 Herdr:
+
+```bash
+ssh you@server
+herdr
+```
+
+同一个持久的 Herdr 会话就会在手机终端中打开。TUI 会适应窄屏,所以你可以在不离开 SSH 的情况下检查智能体、切换工作区、查看窗格。
+
+在 iPhone 上,[moshi](https://getmoshi.app/) 这类应用表现很好。
+
+<div class="mobile-doc-shots">
+ <figure>
+ <img src="/assets/mobile-agent-session-v2.jpeg" alt="手机上通过 SSH 的 Herdr 智能体会话" loading="lazy" />
+ <figcaption>SSH 上的智能体会话</figcaption>
+ </figure>
+ <figure>
+ <img src="/assets/mobile-switch-menu-v2.jpeg" alt="手机上 Herdr 的响应式切换菜单" loading="lazy" />
+ <figcaption>响应式切换菜单</figcaption>
+ </figure>
+</div>
+
+## 从本地终端远程工作
+
+不先打开 shell,直接通过 SSH 连接:
+
+```bash
+herdr --remote workbox
+herdr --remote ssh://you@server:2222
+```
+
+你本地的 Herdr 充当瘦客户端。它通过 SSH 连接,启动或连接远程 Herdr 服务器,并把 UI 流式传回你的本地终端。
+
+想让远程会话用起来像本地时,用这条路径。客户端运行在你的机器上,所以图像剪贴板粘贴等本地桌面功能可以桥接到远程服务器。如果你先 SSH 再在服务器上运行 `herdr`,Herdr 就完全运行在那台服务器上,无法读取你本地桌面的剪贴板。
+
+对于经常连接的目标,把主机写进 SSH 配置:
+
+```text
+Host workbox
+ HostName server.example.com
+ User you
+ Port 2222
+```
+
+然后这样连接:
+
+```bash
+herdr --remote workbox
+```
+
+## 该用哪条路径
+
+本地工作用 `herdr`。想让 Herdr 在远程 shell 上表现得像 tmux,或者在用手机 SSH 客户端时,用 `ssh you@server` 再 `herdr`。想要一个连接远程会话的本地瘦客户端 (包括本地剪贴板图像粘贴桥接) 时,用 `herdr --remote <host>`。
+
+关于远程引导细节、命名远程会话、自定义二进制、直接终端附加和 `--no-session`,参见[持久化与远程访问](/zh-cn/docs/persistence-remote/)。
diff --git a/website/src/content/docs/zh-cn/index.mdx b/website/src/content/docs/zh-cn/index.mdx
new file mode 100644
index 00000000..b62a2b02
--- /dev/null
+++ b/website/src/content/docs/zh-cn/index.mdx
@@ -0,0 +1,77 @@
+---
+title: Herdr 文档
+description: 面向 AI 编程智能体的终端工作区管理器。
+template: splash
+hero:
+ tagline: "安装、学习和配置 Herdr。从适合你的路径开始 — 无需任何终端复用器经验。"
+ image:
+ file: ../../../../public/assets/logo.svg
+ actions:
+ - text: 安装 Herdr
+ link: /zh-cn/docs/install/
+ - text: 快速开始
+ link: /zh-cn/docs/quick-start/
+ variant: secondary
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+## 选择你的路径
+
+<CardGrid>
+ <Card title="第一次接触终端复用器?">
+ 上手不需要学习快捷键。Herdr 以鼠标为先: 点击窗格、拖动边框、通过右键菜单分割和切换。
+
+ [快速开始 →](/zh-cn/docs/quick-start/)
+ </Card>
+ <Card title="从 tmux 或 zellij 迁移过来?">
+ 这套模型你已经很熟悉了。前缀键是 `ctrl+b`,窗格会持久保留,分离和重新连接的行为都符合你的预期。
+
+ [核心概念 →](/zh-cn/docs/concepts/) · [按键绑定 →](/zh-cn/docs/configuration/#按键绑定)
+ </Card>
+</CardGrid>
+
+## 或者让你的智能体来介绍
+
+已经在用 AI 编程智能体?让它来帮你完成入门。粘贴这个提示词:
+
+```text
+Help me understand and set up Herdr. Read https://herdr.dev/agent-guide.md first, then walk me through it step by step.
+```
+
+这份指南会教你的智能体 Herdr 的概念、安装、配置和常见问题的修复方法,让它的回答保持准确,而不是即兴发挥。
+
+## 核心指南
+
+<CardGrid>
+ <Card title="智能体">
+ 了解受支持的智能体、检测行为、集成、自定义标签和直接附加。
+
+ [理解智能体 →](/zh-cn/docs/agents/)
+ </Card>
+ <Card title="会话状态">
+ 理解分离、重启恢复、窗格历史回放、智能体原生会话恢复和实时交接。
+
+ [对比状态路径 →](/zh-cn/docs/session-state/)
+ </Card>
+ <Card title="配置">
+ 配置按键绑定、主题、侧边栏行为、通知、回滚缓冲和高级选项。
+
+ [配置 Herdr →](/zh-cn/docs/configuration/)
+ </Card>
+ <Card title="API">
+ 通过 CLI 和本地 socket API,从脚本、工具和智能体控制 Herdr。
+
+ [阅读 API 指南 →](/zh-cn/docs/socket-api/)
+ </Card>
+ <Card title="插件">
+ 编写本地可执行的工作流插件,带有清单声明的动作和事件钩子。
+
+ [编写插件 →](/zh-cn/docs/plugins/)
+ </Card>
+ <Card title="插件市场">
+ 现在就可以从 GitHub 分享插件,为仓库打上主题标签,插件市场上线时即可收录。
+
+ [发布插件 →](/zh-cn/docs/marketplace/)
+ </Card>
+</CardGrid>
diff --git a/website/src/content/docs/zh-cn/install.mdx b/website/src/content/docs/zh-cn/install.mdx
new file mode 100644
index 00000000..de84bfc5
--- /dev/null
+++ b/website/src/content/docs/zh-cn/install.mdx
@@ -0,0 +1,151 @@
+---
+title: 安装 Herdr
+description: 在 Linux、macOS 和 Windows 测试版上安装、更新和验证 Herdr。
+---
+
+Herdr 为 Linux 和 macOS 提供稳定版二进制文件。Windows 原生支持是仅限预览版的测试版。
+
+## 安装
+
+在 Linux 或 macOS 上运行:
+
+```bash
+curl -fsSL https://herdr.dev/install.sh | sh
+```
+
+在 Windows 预览测试版上,安装预览通道:
+
+```powershell
+powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
+```
+
+安装器会下载适合你平台的发布二进制文件并放到 PATH 上。Windows 安装器默认使用预览通道,把该通道写入 Herdr 配置,使用带版本号的安装文件夹,并更新一个 `current` 联接点,因此更新时不需要覆盖正在运行的 `herdr.exe`。
+
+## 用 Homebrew 安装
+
+如果你已经在用 Homebrew:
+
+```bash
+brew install herdr
+```
+
+## 用 mise 安装
+
+如果你已经在用 mise:
+
+```bash
+mise use -g herdr
+```
+
+如果 mise 报 `herdr not found in mise tool registry`,请更新 mise 后重试。旧版 mise 早于 Herdr 的注册表条目;`mise use -g github:ogulcancelik/herdr` 可以作为临时兜底。
+
+## 用 Nix 安装
+
+如果你已经在用 Nix,Herdr 提供了一个从源码构建的 flake:
+
+```bash
+nix run github:ogulcancelik/herdr/v0.x.y
+nix build github:ogulcancelik/herdr/v0.x.y
+nix profile install github:ogulcancelik/herdr/v0.x.y
+```
+
+把 `v0.x.y` 替换为最新的发布标签。省略标签可以跟踪 `master`,但常规安装建议使用发布标签。
+
+flake 还提供一个开发 shell:
+
+```bash
+nix develop github:ogulcancelik/herdr
+```
+
+更新时使用你安装 Herdr 的同一套 Nix 工作流。对于 profile 安装,列出 profile 条目并升级 Herdr 条目:
+
+```bash
+nix profile list
+nix profile upgrade <index-or-name>
+```
+
+如果 Herdr 是你自己 flake 的一个 input,更新该 input 并重建你的系统、Home Manager 或开发环境:
+
+```bash
+nix flake update herdr
+```
+
+## 手动下载
+
+也可以从 [GitHub releases](https://github.com/ogulcancelik/herdr/releases) 下载二进制文件。
+
+选择匹配你系统的产物:
+
+| 系统 | 产物 |
+| --- | --- |
+| Linux x86_64 | `herdr-linux-x86_64` |
+| Linux aarch64 | `herdr-linux-aarch64` |
+| macOS Intel | `herdr-macos-x86_64` |
+| macOS Apple silicon | `herdr-macos-aarch64` |
+
+在 Linux 或 macOS 上,赋予可执行权限并移动到 PATH 上的某个位置。
+
+```bash
+chmod +x herdr-linux-x86_64
+mv herdr-linux-x86_64 ~/.local/bin/herdr
+```
+
+### Windows 测试版下载
+
+在 Windows 原生支持处于测试阶段期间,Windows 二进制文件只在预览版发布中提供。常规测试请使用上面的预览安装器,或从预览的 GitHub 预发布中下载 Windows 产物:
+
+| 系统 | 产物 |
+| --- | --- |
+| Windows x86_64 测试版 | `herdr-windows-x86_64.exe` |
+
+## 验证
+
+启动 Herdr:
+
+```bash
+herdr
+```
+
+如果 shell 找不到 `herdr`,重启终端,或检查安装目录是否在 PATH 上。
+
+## 更新
+
+Herdr 会检查新版本并在应用内通知你。也可以手动更新:
+
+```bash
+herdr update
+```
+
+`herdr update` 适用于由 Herdr 自带安装器管理的安装。Homebrew、mise 和 Nix 安装请改用那些包管理器更新。
+
+在 Linux 和 macOS 上,Herdr 默认使用稳定更新通道。要启用来自 `master` 的预览构建,设置通道:
+
+```bash
+herdr channel set preview
+```
+
+用同样的方式把 Linux 和 macOS 的直接安装切回稳定版:
+
+```bash
+herdr channel set stable
+```
+
+对于直接安装,切换通道时也会检查该通道并安装其最新二进制文件。如果该更新失败,运行 `herdr update` 从配置的通道重试。
+
+预览构建是从当前开发分支手动发布的 GitHub 预发布。当你想在下一个稳定版之前拿到修复时很有用,但它们可能出现回归。Homebrew、mise 和 Nix 安装不使用预览通道。
+
+Windows 测试版构建目前仅限预览通道。在稳定的 Windows 发布可用之前,Windows 上的 `herdr channel set stable` 会被拒绝。
+
+默认情况下,`herdr update` 安装新二进制文件,并不打扰兼容的运行中会话。如果某次更新改变了 Herdr 的客户端/服务器协议,Herdr 会在安装后询问是否停止旧服务器。要使用新版本,请停止旧服务器。停止会退出窗格进程。对于默认会话,运行 `herdr server stop`,再运行 `herdr`。对于命名会话,运行 `herdr session stop <name>`,再运行 `herdr session attach <name>`。
+
+要对受支持的运行中会话启用实验性的实时服务器交接,运行:
+
+```bash
+herdr update --handoff
+```
+
+实时交接不适用于 Homebrew、mise 或 Nix 的包管理器更新。这些安装先用包管理器更新,然后在准备好使用新服务器时重启那个 Herdr 会话。如果运行中的会话仍在使用旧服务器,用 `herdr server stop` 或 `herdr session stop <name>` 停止它,再重新运行 Herdr。
+
+## 系统要求
+
+Herdr 稳定版支持 Linux 和 macOS。Windows 原生构建是仅限预览版的测试版发布;受支持的工作流和已知限制见 [Windows 测试版](/zh-cn/docs/windows-beta/)。
diff --git a/website/src/content/docs/zh-cn/integrations.mdx b/website/src/content/docs/zh-cn/integrations.mdx
new file mode 100644
index 00000000..5ad8fa92
--- /dev/null
+++ b/website/src/content/docs/zh-cn/integrations.mdx
@@ -0,0 +1,286 @@
+---
+title: 集成
+description: 为 Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、Qoder CLI 和 Cursor Agent CLI 安装 Herdr 集成。
+---
+
+Herdr 自动检测受支持的智能体。官方集成可以额外提供用于恢复的原生会话身份、生命周期状态上报,或两者兼有。
+
+当你想要 Claude Code/Codex/Copilot/Devin 式钩子的智能体原生会话恢复、Pi/OMP/Kimi/OpenCode/Kilo/Hermes 式钩子或插件的直接生命周期上报,或两者都要时,使用集成。完整的状态权威模型见[智能体](/zh-cn/docs/agents/)。
+
+## 安装集成
+
+在 Herdr 中打开设置,用集成标签页为 `PATH` 上发现的智能体安装推荐集成,或手动运行命令:
+
+```bash
+herdr integration install pi
+herdr integration install omp
+herdr integration install claude
+herdr integration install codex
+herdr integration install copilot
+herdr integration install devin
+herdr integration install droid
+herdr integration install kimi
+herdr integration install opencode
+herdr integration install kilo
+herdr integration install hermes
+herdr integration install qodercli
+herdr integration install cursor
+```
+
+## 卸载集成
+
+```bash
+herdr integration uninstall pi
+herdr integration uninstall omp
+herdr integration uninstall claude
+herdr integration uninstall codex
+herdr integration uninstall copilot
+herdr integration uninstall devin
+herdr integration uninstall droid
+herdr integration uninstall kimi
+herdr integration uninstall opencode
+herdr integration uninstall kilo
+herdr integration uninstall hermes
+herdr integration uninstall qodercli
+herdr integration uninstall cursor
+```
+
+## Herdr 如何使用集成
+
+Herdr 以两种不同方式使用集成:
+
+| 集成类型 | 智能体 | 效果 |
+| --- | --- | --- |
+| 生命周期权威 | Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent | 已安装且在为该窗格主动上报时,由钩子或插件事件决定 `idle`、`working` 和 `blocked`。对同一个生命周期权威,Herdr 不再使用屏幕清单兜底。 |
+| 会话身份 | Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Qoder CLI、Cursor Agent CLI | 集成上报用于恢复的原生会话引用。状态仍来自 Herdr 的屏幕清单检测。 |
+
+自定义 socket 集成在定义了原生终端 UI 中不可见的状态时,也可以上报状态。
+
+一些集成会上报智能体的原生会话引用。除非被 `[session] resume_agents_on_restore = false` 禁用,Herdr 会在服务器重启后使用官方会话引用恢复 Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Cursor Agent CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode 和 Kilo Code CLI 的窗格。
+
+原生会话恢复需要最新的 Herdr 集成: Pi 集成版本 `2`、OMP 版本 `3`、Claude Code 版本 `6`、Codex 版本 `5`、GitHub Copilot CLI 版本 `2`、Devin CLI 版本 `2`、Droid 版本 `2`、Kimi Code CLI 版本 `3`、Qoder CLI 版本 `2`、Cursor Agent CLI 版本 `1`、OpenCode 版本 `5`、Kilo Code CLI 版本 `1`、Hermes Agent 版本 `2`。用 `herdr integration status` 查看已安装版本。
+
+## Pi
+
+安装 Pi 集成:
+
+```bash
+herdr integration install pi
+```
+
+Herdr 把内置扩展写入:
+
+```text
+~/.pi/agent/extensions/herdr-agent-state.ts
+```
+
+如果设置了 `PI_CODING_AGENT_DIR`,Herdr 会改为写入 `$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts`。extensions 目录必须已经存在。卸载只删除那个扩展文件。
+
+## OMP
+
+安装 OMP 集成:
+
+```bash
+herdr integration install omp
+```
+
+Herdr 把内置扩展写入:
+
+```text
+~/.omp/agent/extensions/herdr-omp-agent-state.ts
+```
+
+如果设置了 `PI_CODING_AGENT_DIR`,Herdr 会改为写入 `$PI_CODING_AGENT_DIR/extensions/herdr-omp-agent-state.ts`。extensions 目录必须已经存在。卸载只删除那个扩展文件。
+
+OMP 集成通过 Herdr 的 socket API 上报智能体标签 `omp`、生命周期状态和原生会话身份。它不需要对 `omp` 可执行文件做原生进程检测,并且 Herdr 可以在服务器重启后用 `omp --resume=<session>` 恢复 OMP 窗格。
+
+## Claude Code
+
+安装 Claude Code 钩子:
+
+```bash
+herdr integration install claude
+```
+
+该钩子在会话启动时把 Claude Code 的会话身份上报给本地 Herdr socket。Claude Code 的状态来自 Herdr 的屏幕清单检测。
+
+Herdr 默认使用 `~/.claude`,设置了 `CLAUDE_CONFIG_DIR` 时使用后者。Claude 配置目录必须已经存在。安装会写入 `hooks/herdr-agent-state.sh`,并向 `settings.json` 添加 Herdr 钩子条目。卸载会移除匹配的钩子条目并删除钩子脚本。
+
+## Codex
+
+安装 Codex 钩子:
+
+```bash
+herdr integration install codex
+```
+
+Codex 钩子通过与其他集成相同的本地 socket API 上报会话身份。Codex 的状态来自 Herdr 的屏幕清单检测。
+
+Herdr 默认使用 `~/.codex`,设置了 `CODEX_HOME` 时使用后者。Codex 配置目录必须已经存在。安装会写入 `herdr-agent-state.sh`、更新 `hooks.json`,并确保 `config.toml` 中有 `[features] hooks = true`。如果存在已弃用的顶层 `codex_hooks` 标志,它也会一并移除。卸载会从 `hooks.json` 中移除 Herdr 条目并删除钩子脚本,但不改动 `config.toml`。
+
+## GitHub Copilot CLI
+
+安装 GitHub Copilot CLI 钩子:
+
+```bash
+herdr integration install copilot
+```
+
+Copilot 钩子通过与其他集成相同的本地 socket API 上报会话身份。Copilot 的状态来自 Herdr 的屏幕清单检测。
+
+Herdr 默认使用 `~/.copilot`,设置了 `COPILOT_HOME` 时使用后者。Copilot 配置目录必须已经存在。安装会写入 `hooks/herdr-agent-state.sh`,并向 `settings.json` 添加一个 `SessionStart` 钩子条目。卸载会从 `settings.json` 中移除 Herdr 条目并删除钩子脚本。
+
+在 Copilot 发出携带会话信息的事件后,Herdr 可以用上报的会话 id 通过 `copilot --resume=<id>` 恢复该窗格。
+
+## Devin CLI
+
+安装 Devin CLI 钩子:
+
+```bash
+herdr integration install devin
+```
+
+该钩子从 Devin 的会话、提示、工具使用、权限和停止事件中上报原生会话身份。Devin 的状态仍来自 Herdr 的屏幕清单和 OSC 检测,因为 Devin 钩子不会在每次权限取消或用户中断后都发出可靠的状态转换。
+
+Herdr 默认使用 `~/.config/devin`,设置了 `XDG_CONFIG_HOME` 时使用 `$XDG_CONFIG_HOME/devin`。Devin 配置目录必须已经存在。安装会写入 `herdr-agent-state.sh`,并向 `config.json` 添加 Herdr 钩子条目。钩子在 Devin 运行期间刷新会话引用。卸载会从 `config.json` 中移除 Herdr 条目并删除钩子脚本。
+
+Herdr 用 `devin --resume <id>` 恢复保存的 Devin 会话。无论钩子是否安装,屏幕清单检测始终是状态权威。
+
+## Kimi Code CLI
+
+安装 Kimi Code CLI 钩子:
+
+```bash
+herdr integration install kimi
+```
+
+该钩子向 Herdr 上报 Kimi 的会话身份和生命周期状态,用于原生恢复和权威的 `idle`、`working`、`blocked` 状态。需要 Kimi Code CLI `0.14.0` 或更新版本。
+
+Herdr 默认使用 `~/.kimi-code`,设置了 `KIMI_CODE_HOME` 时使用后者。Kimi Code 配置目录必须已经存在。安装会写入 `hooks/herdr-agent-state.sh`,并在 `config.toml` 中追加 Herdr 管理的 `[[hooks]]` 条目。卸载会移除 Herdr 管理的配置块并删除钩子脚本。
+
+Herdr 用 `kimi --session <id>` 恢复保存的 Kimi 会话。
+
+## Droid
+
+安装 Droid 钩子:
+
+```bash
+herdr integration install droid
+```
+
+Droid 钩子通过与其他集成相同的本地 socket API 上报会话身份。生命周期状态仍来自 Herdr 的屏幕清单检测,因为 Droid 钩子没有覆盖所有生命周期转换。
+
+Herdr 的 Droid 钩子使用 `~/.factory`。Factory 配置目录必须已经存在。安装会写入 `hooks/herdr-agent-state.sh`,向 `settings.json` 添加 Herdr 的 `SessionStart` 钩子条目,并在 `hooks.json` 中存在旧的 Herdr Droid 钩子条目时将其移除。卸载会从两个配置文件中移除 Herdr 条目并删除钩子脚本。
+
+在 Droid 发出会话启动事件后,Herdr 可以用上报的会话 id 通过 `droid --resume <id>` 恢复该窗格。
+
+## OpenCode
+
+安装 OpenCode 插件:
+
+```bash
+herdr integration install opencode
+```
+
+Herdr 把插件写入 `~/.config/opencode/plugins/herdr-agent-state.js`。OpenCode 配置目录必须已经存在。卸载只删除那个插件文件。
+
+该插件在 OpenCode 运行于 Herdr 窗格内时上报生命周期状态和会话身份。在 OpenCode 发出携带会话信息的事件后,Herdr 可以用上报的会话 id 通过 `opencode --session <id>` 恢复该窗格。插件未安装时,屏幕清单检测仍然可用。
+
+## Kilo Code CLI
+
+安装 Kilo Code CLI 插件:
+
+```bash
+herdr integration install kilo
+```
+
+Herdr 把插件写入 `~/.config/kilo/plugin/herdr-agent-state.js`。Kilo 配置目录必须已经存在。卸载只删除那个插件文件。
+
+该插件在 Kilo 运行于 Herdr 窗格内时上报生命周期状态和会话身份。在 Kilo 发出携带会话信息的事件后,Herdr 可以用上报的会话 id 通过 `kilo --session <id>` 恢复该窗格。插件未安装时,屏幕清单检测仍然可用。
+
+## Hermes Agent
+
+安装 Hermes Agent 插件:
+
+```bash
+herdr integration install hermes
+```
+
+Herdr 写入 `~/.hermes/plugins/herdr-agent-state/`,并在 `~/.hermes/config.yaml` 中启用 `herdr-agent-state`。Hermes 配置目录必须已经存在。安装后请重启 Hermes 以加载插件。卸载会删除插件目录,并从 `plugins.enabled` 中移除 `herdr-agent-state`。
+
+该插件在 Hermes 运行于 Herdr 窗格内时上报生命周期、工具、审批状态和会话 id。Herdr 可以用上报的会话 id 通过 `hermes --resume <id>` 恢复该窗格。插件未安装时,屏幕清单检测仍然可用。
+
+## Qoder CLI
+
+安装 Qoder CLI 钩子:
+
+```bash
+herdr integration install qodercli
+```
+
+该钩子向 Herdr 上报 Qoder CLI 的会话身份,用于原生恢复。生命周期状态仍来自 Herdr 的屏幕清单检测,因为 Qoder 钩子没有覆盖所有生命周期转换。
+
+Herdr 默认使用 `~/.qoder`,设置了 `QODER_CONFIG_DIR` 时使用后者。Qoder 配置目录必须已经存在。安装会写入 `hooks/herdr-agent-state.sh`,并向 `settings.json` 添加 Herdr 钩子条目。卸载会移除匹配的钩子条目并删除钩子脚本。
+
+Herdr 用 `qodercli --resume <id>` 恢复保存的 Qoder CLI 会话。
+
+钩子未安装时,屏幕清单检测仍然可用。
+
+## Cursor Agent CLI
+
+安装 Cursor Agent CLI 钩子:
+
+```bash
+herdr integration install cursor
+```
+
+该钩子在 Cursor Agent CLI 运行于 Herdr 窗格内时,通过 Cursor 的 `sessionStart` 钩子上报会话身份。Cursor 的状态来自 Herdr 的屏幕清单检测。
+
+Herdr 默认使用 `~/.cursor`,设置了 `CURSOR_CONFIG_DIR` 时使用后者。Cursor 配置目录必须已经存在。安装会写入 `herdr-agent-state.sh`,并向 `hooks.json` 添加 Herdr 的 `sessionStart` 条目。卸载会移除匹配的钩子条目并删除钩子脚本。
+
+在 Cursor 发出会话启动事件后,Herdr 可以用上报的会话 id 通过 `cursor-agent --resume <id>` 恢复该窗格。Herdr 恢复窗格时,`cursor-agent` 命令必须在 `PATH` 上;Herdr 不会启动通用的 `agent` 命令。
+
+## 自定义状态标签
+
+集成可以上报一个简短的视觉标签,而不改变语义状态。
+
+例如,一个智能体可以在语义上保持 `working`,同时在 UI 中显示 `indexing`。
+
+```bash
+herdr pane report-agent w1:p1 \
+ --source custom:docs \
+ --agent docs-bot \
+ --state working \
+ --custom-status indexing
+```
+
+与 Herdr 管理的集成并行运行的用户钩子,应该使用元数据而不是 `report-agent`。元数据只改变展示,不会夺走集成对 `idle`、`working`、`blocked` 或会话恢复的权威。`--agent` 是守卫,使上报只在该权威智能体处于活动状态时生效。`--applies-to-source` 是守卫,使上报只在该生命周期权威来源处于活动状态时生效。`--display-agent` 修改显示名称。
+
+```bash
+herdr pane report-metadata "$HERDR_PANE_ID" \
+ --source user:claude-title \
+ --agent claude \
+ --title "Refactor auth middleware" \
+ --display-agent "Claude: auth" \
+ --custom-status "refactor auth" \
+ --state-label working="refactoring auth" \
+ --ttl-ms 3600000
+```
+
+自定义状态和状态标签只影响视觉。等待、通知和工作区汇总仍使用语义状态。
+
+## 调试集成状态
+
+列出已知的智能体:
+
+```bash
+herdr agent list
+```
+
+需要验证 Herdr 能看到什么时,读取窗格:
+
+```bash
+herdr pane read w1:p1 --source recent --lines 50
+```
+
+如果集成状态看起来不对,先确认智能体运行在 Herdr 内部,并且相关的钩子或插件是为同一个用户账号安装的。
diff --git a/website/src/content/docs/zh-cn/keyboard.mdx b/website/src/content/docs/zh-cn/keyboard.mdx
new file mode 100644
index 00000000..21ae60bd
--- /dev/null
+++ b/website/src/content/docs/zh-cn/keyboard.mdx
@@ -0,0 +1,112 @@
+---
+title: 键盘
+description: 前缀键是什么、应该先学哪些绑定,以及如何做到不用前缀键。
+---
+
+:::tip[从 tmux 或 zellij 迁移过来?]
+这套模型你已经很熟悉了。直接跳到[按键绑定参考](/zh-cn/docs/configuration/#按键绑定)查看完整的默认键位和配置语法。
+:::
+
+Herdr 是鼠标原生的。你可以点击窗格、标签页、工作区和智能体,拖动分割边框,使用右键菜单,一个按键绑定都不用学。键盘操作是可选的一层,不是必需项。
+
+## 前缀键是什么
+
+终端复用器位于终端和其中运行的程序之间。这些程序已经占用了大多数按键组合: `ctrl+c` 中断,`ctrl+r` 搜索历史,编辑器几乎占用了剩下的一切。如果 Herdr 直接抢占常用按键,就会破坏其中运行的程序。
+
+前缀键解决了这个问题。按下前缀键 (默认 `ctrl+b`),下一次按键会发给 Herdr 而不是终端。`prefix+c` 的意思是: 按下 `ctrl+b`,松开,再按 `c`。只保留一个键,而不是几十个。
+
+随时按 `prefix+?` 可以查看所有生效的绑定。
+
+## 先学这五个
+
+| 动作 | 按键 |
+| --- | --- |
+| 新建标签页 | `prefix+c` |
+| 向右 / 向下分割 | `prefix+v` / `prefix+minus` |
+| 在窗格间移动 | `prefix+h/j/k/l` |
+| 工作区导航 | `prefix+w` |
+| 分离并让一切继续运行 | `prefix+q` |
+
+这些覆盖了日常的大部分移动操作。其余的都可以继续用鼠标。
+
+## 其余的,按任务分
+
+窗格:
+
+| 动作 | 按键 |
+| --- | --- |
+| 缩放聚焦的窗格 | `prefix+z` |
+| 关闭窗格 | `prefix+x` |
+| 交换窗格 | `prefix+shift+h/j/k/l` |
+| 调整大小模式 | `prefix+r` |
+| 复制模式 | `prefix+[` |
+
+标签页:
+
+| 动作 | 按键 |
+| --- | --- |
+| 下一个 / 上一个标签页 | `prefix+n` / `prefix+p` |
+| 跳转到标签页 1–9 | `prefix+1..9` |
+| 重命名标签页 | `prefix+shift+t` |
+| 关闭标签页 | `prefix+shift+x` |
+
+工作区与会话:
+
+| 动作 | 按键 |
+| --- | --- |
+| 新建工作区 | `prefix+shift+n` |
+| 重命名工作区 | `prefix+shift+w` |
+| 关闭工作区 | `prefix+shift+d` |
+| Goto 选择器 | `prefix+g` |
+| 切换侧边栏 | `prefix+b` |
+
+完整键位和绑定语法见[按键绑定参考](/zh-cn/docs/configuration/#按键绑定)。
+
+## 复制模式
+
+按 `prefix+[` 让聚焦的窗格进入复制模式。用 `h/j/k/l`、`w/b/e` 和 `{`/`}` 移动,用 `v` 或空格开始选择,用 `y` 或回车复制,用 `q` 或 Esc 不复制直接退出。鼠标拖选可以直接复制,完全不用进入复制模式。
+
+## 一切都可以改
+
+每个绑定都可以配置,包括前缀键本身:
+
+```toml
+[keys]
+prefix = "ctrl+a"
+```
+
+## 不用前缀键
+
+你可以把 Herdr 动作绑定到完全不需要前缀的直接组合键。难点在于知道哪些组合键是安全的,因为终端、shell 和桌面环境已经占用了键盘的大部分。
+
+任何组合键都可以做绑定: `ctrl+j`、`alt+k`,顺手就行。但一个组合键要经过三层才能到达 Herdr: 操作系统、外层终端 (Ghostty、iTerm2 等都带有自己的默认键位),以及窗格内运行的程序。`ctrl+j` 能顺利到达 Herdr,但 shell 和编辑器把它当作回车。`alt+k` 在 Linux 上是空闲的,但在 macOS 的大多数终端里会被组合成特殊字符。如果你从这些键系里选组合键,请对照自己的终端和系统快捷键再确认一遍。
+
+我们梳理了 Ghostty、iTerm2、Terminal.app、kitty、WezTerm、Alacritty、Warp、Windows Terminal、GNOME Terminal 和 Konsole 的默认按键绑定,以及 GNOME 和 KDE 的全局快捷键。有一个修饰键系几乎在所有地方都没被占用: `ctrl+alt`。终端把它留空,它不受 macOS option 键组合行为 (会挡掉纯 `alt` 组合键) 的影响,而且即使在没有现代键盘协议的终端里也能正常传输。它是安全的默认推荐;选择权在你。
+
+下面的配置保留前缀绑定,并在其上叠加直接组合键:
+
+```toml
+[keys]
+focus_pane_left = ["prefix+h", "ctrl+alt+h"]
+focus_pane_down = ["prefix+j", "ctrl+alt+j"]
+focus_pane_up = ["prefix+k", "ctrl+alt+k"]
+focus_pane_right = ["prefix+l", "ctrl+alt+l"]
+previous_tab = ["prefix+p", "ctrl+alt+["]
+next_tab = ["prefix+n", "ctrl+alt+]"]
+new_tab = ["prefix+c", "ctrl+alt+c"]
+split_vertical = ["prefix+v", "ctrl+alt+d"]
+split_horizontal = ["prefix+minus", "ctrl+alt+shift+d"]
+zoom = ["prefix+z", "ctrl+alt+z"]
+```
+
+少数 `ctrl+alt` 组合键已被其他地方占用。请避开这些:
+
+| 组合键 | 占用者 |
+| --- | --- |
+| `ctrl+alt+arrows` | GNOME 工作区切换,Ghostty 和 Konsole 默认键位 |
+| `ctrl+alt+t` | Ubuntu 和 Fedora 的“启动终端” |
+| `ctrl+alt+l` / `ctrl+alt+a` | KDE 锁屏 / 注意力窗口 |
+| `ctrl+alt+s` / `ctrl+alt+u` | Konsole |
+| `ctrl+alt+f1..f12` | Linux 虚拟控制台切换 |
+
+如果某个直接组合键没有任何反应,说明终端或桌面环境在 Herdr 看到它之前就把它消费掉了。两边任选其一重新配置: 在终端设置里释放这个组合键,或者在 Herdr 里换一个。
diff --git a/website/src/content/docs/zh-cn/marketplace.mdx b/website/src/content/docs/zh-cn/marketplace.mdx
new file mode 100644
index 00000000..350cc0d5
--- /dev/null
+++ b/website/src/content/docs/zh-cn/marketplace.mdx
@@ -0,0 +1,44 @@
+---
+title: 插件市场
+description: 在 GitHub 上发现社区 Herdr 插件,并让你自己的插件被收录。
+---
+
+Herdr 插件市场是一个可供发现的社区插件索引。
+访问 [herdr.dev/plugins](/plugins/) 浏览。它是公开 GitHub 仓库的自动索引,
+而不是经过审核的目录。
+
+## 浏览插件
+
+[插件市场](/plugins/)会列出所有打了 GitHub 主题标签 `herdr-plugin` 的公开仓库。
+你可以按名称、作者、描述或语言搜索,并按热度、最近活跃度或最新排序。
+每个条目都直接链接到它在 GitHub 上的源码仓库。
+
+收录是自动且未经审核的。被列出只说明仓库给自己打了标签,并不代表 Herdr
+审查过它,所以在安装任何插件之前,请先阅读[信任指南](/zh-cn/docs/plugins/#信任与安全)。
+
+## 安装插件
+
+插件市场是在安装之上增加的发现渠道,它不会取代安装。任何插件都可以直接从
+GitHub 安装:
+
+```bash
+herdr plugin install owner/repo[/subdir...]
+```
+
+发布一个普通的公开 GitHub 仓库,在根目录或子目录放一个 `herdr-plugin.toml`
+清单,这条命令就能用了。清单和编写参考见[插件](/zh-cn/docs/plugins/)。
+
+## 让你的插件被收录
+
+给公开仓库添加 GitHub 主题标签 `herdr-plugin`。索引只使用这一个信号,
+所以给公开插件打上标签就够了。索引每 30 分钟自动刷新,新打标签的仓库很快
+就会出现,去掉标签的仓库会在下一次刷新时消失。
+
+## 条目会展示什么
+
+每张卡片展示 GitHub 仓库的元数据: 仓库名和作者、描述、star 数、主要语言、
+最后 push 时间,以及指回源码的链接。索引从 GitHub 的仓库搜索读取这些信息,
+所以保持仓库描述和主题标签的准确,是让条目有用的关键。
+
+索引目前还不会解析 `herdr-plugin.toml`,所以插件 `id`、声明的 `platforms`、
+`min_herdr_version` 等清单字段在 v1 中不会展示。Fork 和已归档的仓库会被排除。
diff --git a/website/src/content/docs/zh-cn/persistence-remote.mdx b/website/src/content/docs/zh-cn/persistence-remote.mdx
new file mode 100644
index 00000000..a81a8469
--- /dev/null
+++ b/website/src/content/docs/zh-cn/persistence-remote.mdx
@@ -0,0 +1,132 @@
+---
+title: 持久化与远程访问
+description: 从 Herdr 分离、稍后重新连接、使用命名会话,以及通过 SSH 连接。
+---
+
+Herdr 让窗格在后台服务器中持续运行。你的终端客户端可以分离,稍后再重新连接。
+
+关于本地、SSH 和 `herdr --remote` 工作流,参见[使用 Herdr 的工作方式](/zh-cn/docs/how-to-work/)。
+
+## 分离与重新连接
+
+用 `ctrl+b q` 分离客户端;窗格和智能体继续运行。再次运行 `herdr` 即可重新连接。用 `herdr server stop` 停止会话及其窗格。
+
+在服务器完全停止后再次启动时,Herdr 会恢复保存的会话形态。关于分离、服务器重启、屏幕历史回放、智能体原生会话恢复和实时交接各自能保留什么,参见[会话状态与恢复](/zh-cn/docs/session-state/)。
+
+## 命名会话
+
+需要相互独立的 Herdr 服务器时,使用命名会话。
+
+```bash
+herdr session list
+herdr session attach work
+herdr session attach side-project
+herdr session stop work
+herdr session delete side-project
+```
+
+命名会话拥有自己的窗格、标签页、工作区、socket 和运行时状态。它仍然共享同一个全局配置文件。
+
+脚本中使用 `--json`:
+
+```bash
+herdr session list --json
+herdr session stop work --json
+herdr session delete side-project --json
+```
+
+## 通过 SSH 远程连接
+
+远程模式有两种;[使用 Herdr 的工作方式](/zh-cn/docs/how-to-work/)对它们做了比较。tmux 风格的路径是 SSH 到服务器并在那里运行 `herdr`。另一种是从本地机器通过 SSH 连接:
+
+```bash
+herdr --remote workbox
+herdr --remote ssh://you@server:2222
+```
+
+这种模式下,你本地的 Herdr 是瘦客户端。它通过 SSH 连接,启动或连接远程 Herdr 服务器,并把 UI 流式传回本地终端。因为客户端在本地运行,Herdr 可以把图像剪贴板粘贴等本地桌面功能桥接到远程会话: 把图像复制到远程临时文件,再粘贴该路径。
+
+默认情况下,`herdr --remote` 在这次连接中使用你本地的 Herdr 按键绑定。即使远程服务器的配置不同,也能保持本地的肌肉记忆。本地按键绑定是连接时的快照;编辑本地按键绑定后请分离再重连。想改用远程服务器配置时,使用 `--remote-keybindings server`。本地的自定义命令按键绑定不会被发送,因为那些命令会在远程主机上执行。
+
+对于经常连接的目标,使用你的 SSH 配置:
+
+```text
+Host workbox
+ HostName server.example.com
+ User you
+ Port 2222
+```
+
+然后这样连接:
+
+```bash
+herdr --remote workbox
+```
+
+远程连接支持 x86_64 和 aarch64 的 Linux 与 macOS 主机。Herdr 会检查远程平台,优先使用远程 `PATH` 上已有的匹配 `herdr`,然后检查 `~/.local/bin/herdr`。如果没有匹配的二进制文件,交互式运行会询问是否安装到 `~/.local/bin/herdr`;非交互式运行则直接失败,不会修改主机。如果 `~/.local/bin` 不在远程 `PATH` 上,Herdr 会在安装后发出警告。
+
+Windows 原生的 `herdr --remote` 不在 Windows 测试版范围内。在 Windows 上请 SSH 到服务器并在那里运行 `herdr`。
+
+默认情况下,`herdr --remote` 通过一个临时 SSH 配置运行桥接: 先包含你的 SSH 配置,再补充兜底的保活设置。已有的用户保活设置优先。设置 `[remote].manage_ssh_config = false` 可以不用 Herdr 生成的桥接配置,而使用普通 `ssh`。
+
+默认情况下,如果需要替换或重启运行中的远程服务器,远程连接使用常规的重启/停止流程。要对受支持的运行中远程服务器启用实验性实时交接,加上 `--handoff`:
+
+```bash
+herdr --remote workbox --handoff
+```
+
+如果你先 SSH 到服务器再在那里运行 `herdr`,Herdr 就完全运行在服务器上。这种模式简单实用,但除了普通的终端文本粘贴之外,它无法访问你本地桌面的剪贴板。
+
+当本地和远程平台一致时,对于直接安装,Herdr 可以直接复制当前本地二进制文件。对于 Homebrew、mise 和 Nix 安装,或平台不一致时,它会从 `https://herdr.dev/latest.json` 下载与当前客户端版本匹配的发布产物。
+
+对于本地构建或自定义二进制文件,在远程连接前设置 `HERDR_REMOTE_BINARY` 指向本地文件路径。
+
+```bash
+HERDR_REMOTE_BINARY=target/release/herdr herdr --remote workbox
+```
+
+## 远程命名会话
+
+用 `--session` 搭配 `--remote` 连接远程主机上的命名会话:
+
+```bash
+herdr --remote workbox --session agents
+```
+
+## 直接终端附加
+
+完整的 Herdr 连接会打开整个工作区 UI。直接附加则在你当前的终端中打开一个由服务器拥有的终端。
+
+在 Windows 测试版中,直接终端附加仅限 Unix。
+
+按智能体目标附加:
+
+```bash
+herdr agent attach reviewer
+```
+
+按终端 ID 附加:
+
+```bash
+herdr terminal attach term_abc123
+```
+
+直接附加先流式传输当前渲染的终端状态,然后是实时 ANSI 帧。输入直接进入该终端。
+
+用 `ctrl+b q` 分离。用 `ctrl+b ctrl+b` 发送字面的 `ctrl+b`。
+
+一个终端只能有一个可写的直接附加客户端拥有输入和调整尺寸的权限。用 `--takeover` 替换现有的所有者:
+
+```bash
+herdr terminal attach term_abc123 --takeover
+```
+
+## 单进程逃生舱
+
+用 `--no-session` 在没有后台服务器/客户端分离的情况下运行 Herdr:
+
+```bash
+herdr --no-session
+```
+
+这主要是调试或兼容性的逃生舱。默认的持久会话模式才是常规路径。
diff --git a/website/src/content/docs/zh-cn/plugins.mdx b/website/src/content/docs/zh-cn/plugins.mdx
new file mode 100644
index 00000000..8d3ba6fc
--- /dev/null
+++ b/website/src/content/docs/zh-cn/plugins.mdx
@@ -0,0 +1,285 @@
+---
+title: 插件
+description: 编写带有清单动作、事件钩子和窗格的本地 Herdr 插件。
+---
+
+Herdr 插件是可分享、可执行的工作流包。插件可以是 Bash 脚本、JavaScript
+应用、Lua 脚本、Rust 二进制,或你机器上能运行的任何 argv 命令。Herdr
+负责宿主侧: 安装、清单校验、按键绑定、终端窗格、事件、调用上下文和
+socket 访问。插件负责自己的实现语言、依赖、文件和持久状态。
+
+插件的存在是为了让 Herdr 保持精简。核心继续专注于终端工作区、窗格、
+智能体和稳定的 CLI/socket API。插件把这套已有的扩展面变成可复用的
+工作流,让大家可以构建、安装和分享,而不必把每种工作流都塞进 Herdr 本体。
+
+插件不是 SDK 集成。它是一个带 `herdr-plugin.toml` 清单和 Herdr 可启动
+命令的目录。Herdr 校验清单、注入运行时上下文、启动声明的命令并记录日志。
+命令在需要做更多工作时,通过 CLI 或 socket 回调 Herdr。
+
+没有单独的插件 SDK,也没有受限的命令集。整个 Herdr CLI 就是插件 API:
+[CLI 参考](/zh-cn/docs/cli-reference/)中的每条命令插件都能用,你自己能以
+`herdr ...` 运行的任何东西,插件也能运行。大多数插件应通过指向运行中
+Herdr 二进制的 `HERDR_BIN_PATH` 调用 Herdr,这样插件在 Unix socket 和
+Windows 命名管道之间保持可移植。想自己发送原始 JSON 请求时,使用
+[socket API](/zh-cn/docs/socket-api/)。
+
+运行时动作注册和非终端的原生插件 UI 不在插件 v1 范围内。动作、事件钩子、
+窗格和链接处理器都在清单中声明。
+
+## 信任与安全
+
+插件是运行在你机器上的普通代码。安装或链接一个插件时,它的构建和运行时
+命令以你的用户身份、在你的环境中执行,并且可以调用完整的 Herdr CLI —
+和你给编辑器、shell 或编程智能体添加的任何扩展一样。这种开放性正是设计
+初衷,加上一点判断力就能保持安全。
+
+从你信任的作者和仓库安装插件,并先大致看看新插件做什么: `herdr-plugin.toml`
+清单,以及它运行的脚本或二进制。`herdr plugin install` 在交互式终端中会
+展示来源和将要运行的命令的预览,你可以在确认前审查。对已经信任的来源用
+`--yes`,想固定某个特定版本时用 `--ref`。
+
+Herdr 校验清单,并把每个插件的配置和状态放在各自的目录中,但它不会审查
+或沙箱化插件的行为。第三方插件来自它们的作者,而不是 Herdr,审查与运行
+由你自行决定。
+
+## 清单
+
+清单是 Herdr 和插件之间的契约。它声明包元数据、支持的平台、可选的构建
+命令,以及 Herdr 可以运行的入口点。
+
+```toml
+id = "example.layout"
+name = "Layout"
+version = "0.1.0"
+min_herdr_version = "0.7.0"
+description = "Apply project layouts"
+platforms = ["linux", "macos", "windows"]
+
+[[build]]
+command = ["npm", "ci"]
+
+[[build]]
+command = ["npm", "run", "build"]
+platforms = ["linux", "macos"]
+
+[[actions]]
+id = "apply"
+title = "Apply layout"
+contexts = ["workspace"]
+command = ["node", "dist/apply.js"]
+
+[[events]]
+on = "worktree.created"
+command = ["herdr", "workspace", "list"]
+
+[[panes]]
+id = "board"
+title = "Project board"
+placement = "overlay"
+command = ["herdr-board"]
+
+[[link_handlers]]
+id = "github-issue"
+title = "Open GitHub issue"
+pattern = "^https://github\\.com/[^/]+/[^/]+/(issues|pull)/[0-9]+$"
+action = "apply"
+```
+
+顶层的 `id`、`name`、`version` 和 `min_herdr_version` 是必填项。
+把 `min_herdr_version` 设为支持你插件所用的插件 API、事件名和清单字段的
+最老 Herdr 版本。当插件的最低版本比当前二进制更新时,Herdr 会拒绝链接
+或安装。`description` 可选。插件 id 可以使用 ASCII 字母、数字、点、
+冒号、下划线和连字符。
+
+动作 id、窗格 id 和链接处理器 id 是插件内部的本地 id。它们可以使用
+ASCII 字母、数字、冒号、下划线和连字符,但不能用点。每种 id 在插件内
+必须唯一。当需要全局唯一名称时,Herdr 会把动作 id 限定为
+`plugin.id.action` 的形式。
+
+用 `platforms = ["linux", "macos", "windows"]` 声明插件可以运行的平台。
+构建命令、动作、事件钩子、窗格和链接处理器也可以声明自己的 `platforms`;
+条目级的 platforms 覆盖顶层列表。没有顶层 `platforms` 的本地插件在链接
+时会给出警告。
+
+`command` 的值是 argv 数组。Herdr 不会通过 shell 运行它们,所以除非你的
+命令自己启动 shell,否则没有 shell 展开。语言相关的行为放到你的脚本或
+二进制里。
+
+## 第一个插件
+
+从一个包含 `herdr-plugin.toml` 和一个可执行脚本或程序的目录开始:
+
+```text
+my-plugin/
+ herdr-plugin.toml
+ index.js
+```
+
+```toml
+id = "example.workspace-tools"
+name = "Workspace Tools"
+version = "0.1.0"
+min_herdr_version = "0.7.0"
+description = "Small workspace helpers"
+platforms = ["linux", "macos", "windows"]
+
+[[actions]]
+id = "list-workspaces"
+title = "List workspaces"
+contexts = ["workspace"]
+command = ["node", "index.js"]
+```
+
+在命令内部通过 `HERDR_BIN_PATH` 回调 Herdr:
+
+```js
+const { spawnSync } = require("node:child_process");
+
+const herdr = process.env.HERDR_BIN_PATH ?? "herdr";
+const result = spawnSync(herdr, ["workspace", "list"], {
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "pipe"],
+});
+
+process.stdout.write(result.stdout);
+process.stderr.write(result.stderr);
+process.exit(result.status ?? 1);
+```
+
+这个示例用了 Node,但插件本身完全不要求 Node。清单可以启动 Bash、
+PowerShell、Python、Rust、Go、Lua、Bun 或用户机器上可用的任何其他命令。
+
+## 安装与链接
+
+安装一个示例插件:
+
+```bash
+herdr plugin install ogulcancelik/herdr-plugin-examples/agent-telegram-notify
+herdr plugin config-dir examples.agent-telegram-notify
+herdr plugin list
+herdr plugin action list --plugin examples.agent-telegram-notify
+```
+
+在本地编写插件时,改为链接工作目录:
+
+```bash
+herdr plugin link /path/to/plugin
+herdr plugin config-dir example.layout
+herdr plugin action list --plugin example.layout
+herdr plugin action invoke example.layout.apply
+herdr plugin pane open --plugin example.layout --entrypoint board
+herdr plugin log list --plugin example.layout
+```
+
+`plugin install` 只接受 GitHub 简写,比如 `owner/repo/subdir`。它用 `git`
+克隆,在交互式终端展示预览,运行受支持的构建命令,然后把检出保存到
+Herdr 管理的插件数据下并注册。非交互式安装用 `--yes`。重新安装 GitHub
+管理的插件会替换该托管检出。不允许覆盖安装到本地链接的插件之上;请先
+unlink 或 uninstall 本地插件。`plugin install` 和 `plugin link` 会创建
+插件的配置和状态目录,`plugin config-dir <id>` 打印配置目录,方便安装
+文档和 shell 脚本使用。
+
+`plugin uninstall <id-or-source>` 注销插件。对 GitHub 管理的安装,它还会
+删除托管检出,并且既接受插件 id,也接受与 install 相同的
+`owner/repo[/subdir...]` 简写。`plugin unlink <id>` 只注销插件、不动文件,
+对本地开发很有用。v1 没有单独的 `plugin update`;要刷新托管插件,请从
+GitHub 重新安装。
+
+示例菜谱仓库是 `ogulcancelik/herdr-plugin-examples`。它在子目录中包含
+多个独立示例插件,包括 `agent-telegram-notify`、`github-link-preview` 和
+`dev-layout-bootstrap`。这些是供复制的示例,不是持续维护的官方插件。
+
+## 构建命令
+
+构建命令在 GitHub `plugin install` 过程中运行,时机在确认之后、Herdr
+注册插件之前。如果构建命令失败,安装中止,插件不会被注册。`plugin link`
+不运行构建命令;本地作者自己构建工作树。构建命令可以生成文件,但在
+安装预览之后修改 `herdr-plugin.toml` 会导致安装中止。构建失败时会显示
+插件 id、构建序号、工作目录、命令、退出状态或 spawn 错误,以及截断后的
+stdout/stderr,不会解读工具输出。
+
+构建命令同样是普通的 argv 命令,但它们不会收到运行时插件上下文或
+Herdr socket 环境变量。插件作者应在文档中说明所需的系统工具,比如
+`cargo`、`npm`、`bun` 或 `lua`;Herdr 报告构建失败,但不会安装缺失的
+工具链。
+
+## 命令与环境
+
+运行时命令以插件目录为工作目录执行。Herdr 注入 `HERDR_SOCKET_PATH`、
+`HERDR_BIN_PATH`、`HERDR_ENV=1`、`HERDR_PLUGIN_ID`、`HERDR_PLUGIN_ROOT`、
+`HERDR_PLUGIN_CONFIG_DIR`、`HERDR_PLUGIN_STATE_DIR`、
+`HERDR_PLUGIN_CONTEXT_JSON`,以及可用时的 `HERDR_WORKSPACE_ID`、
+`HERDR_TAB_ID` 和 `HERDR_PANE_ID`。动作命令还会收到
+`HERDR_PLUGIN_ACTION_ID`;事件钩子收到 `HERDR_PLUGIN_EVENT` 和
+`HERDR_PLUGIN_EVENT_JSON`;窗格命令收到 `HERDR_PLUGIN_ENTRYPOINT_ID`。
+
+`HERDR_PLUGIN_ROOT` 是已安装或已链接的插件目录。不要把用户凭据或持久
+状态放在那里,因为 GitHub 安装的插件根目录是托管的源码检出。把 `.env`
+这类用户可编辑的配置放在 `HERDR_PLUGIN_CONFIG_DIR` 下,把本地运行时
+状态放在 `HERDR_PLUGIN_STATE_DIR` 下。Herdr 会创建这些目录,并在旧版
+插件配置位置存在时把内容初始化到 `HERDR_PLUGIN_CONFIG_DIR`,但不会校验、
+同步或删除其中的内容。文件格式和生命周期归插件所有。
+
+`HERDR_PLUGIN_CONTEXT_JSON` 在本次调用可用时,可以包含工作区、标签页、
+聚焦窗格、worktree、智能体、选中文本、点击的 URL 和链接处理器字段。
+shell 插件可以从各个环境变量读取常用 id,或解析上下文 JSON 获取完整结构。
+
+当插件需要从 Node、PowerShell、Bash 或其他运行时可移植地调用 Herdr 时,
+使用 `HERDR_BIN_PATH`。`HERDR_SOCKET_PATH` 背后的原始 socket 传输是
+操作系统相关的: Unix 客户端连接 Unix socket 路径,Windows 客户端连接
+命名管道。通过 `HERDR_BIN_PATH` 的 CLI 调用可以避开这种传输差异。可用
+命令见 [CLI 参考](/zh-cn/docs/cli-reference/),原始请求结构见
+[socket API](/zh-cn/docs/socket-api/)。
+
+## 窗格
+
+清单中窗格的 `placement` 默认为 `overlay`,它在活动窗格上方打开一个
+临时的缩放覆盖层,关闭时恢复之前的焦点和缩放。`plugin.pane.open` 请求
+可以用 `overlay`、`split`、`tab` 或 `zoomed` 覆盖清单的 placement。
+
+插件窗格打开后就是普通的 Herdr 窗格。插件可以通过 socket 或 CLI 调用
+`pane.move`、`pane.swap`、`pane.resize`、`pane.zoom` 等标准窗格 API;
+窗格跨标签页或工作区移动时,Herdr 会让插件窗格的所有权跟随底层窗格。
+
+在 Windows 上,构建命令、动作命令和事件命令会在裸命令位于 `PATH` 上时
+解析常见的 `PATHEXT` shim,比如 `npm.cmd`、`bun.cmd` 和 `pnpm.cmd`。
+窗格命令使用 Herdr 常规的 Windows 窗格启动器,仍然必须是有效的 Windows
+argv 命令。
+
+## 按键绑定
+
+把某个键绑定到已安装的插件动作:
+
+```toml
+[[keys.command]]
+key = "prefix+l"
+type = "plugin_action"
+command = "example.layout.apply"
+description = "apply layout"
+```
+
+## 链接处理器
+
+用 `[[link_handlers]]` 把对匹配终端 URL 的修饰键点击路由到插件动作,
+而不是在浏览器中打开 URL。修饰键点击的修饰键在所有平台上都是 Control,
+包括 macOS,因为被捕获的终端鼠标上报无法把 Command/Super 和普通点击
+区分开。`pattern` 是对被点击 URL 匹配的 Rust 正则表达式,`action` 必须
+指向同一插件声明的动作。链接处理器动作在 `HERDR_PLUGIN_CONTEXT_JSON`
+中收到 `invocation_source = "link_click"`、`clicked_url` 和
+`link_handler_id`;shell 插件也可以读取 `HERDR_PLUGIN_CLICKED_URL` 和
+`HERDR_PLUGIN_LINK_HANDLER_ID`。每个插件内的处理器按清单顺序检查。
+
+## 存储
+
+v1 没有 Herdr 管理的插件存储 API。需要持久状态的插件应自己管理文件或
+数据库。
+
+## 插件市场
+
+社区插件可以在[插件市场](/plugins/)中发现,它是打了 `herdr-plugin` 主题
+标签的公开 GitHub 仓库的自动索引。插件仍然是普通的 GitHub 仓库: 发布一个
+带 `herdr-plugin.toml` 的仓库,然后分享
+`herdr plugin install owner/repo[/subdir]`。
+
+要让插件被收录,给它的公开仓库添加 GitHub 主题标签 `herdr-plugin`。索引
+每 30 分钟刷新一次。发现机制的工作方式见[插件市场](/zh-cn/docs/marketplace/)。
diff --git a/website/src/content/docs/zh-cn/quick-start.mdx b/website/src/content/docs/zh-cn/quick-start.mdx
new file mode 100644
index 00000000..3f695d92
--- /dev/null
+++ b/website/src/content/docs/zh-cn/quick-start.mdx
@@ -0,0 +1,69 @@
+---
+title: 快速开始
+description: 创建你的第一个 Herdr 工作区,在持久的终端窗格中运行智能体。
+---
+
+如果还没有安装 Herdr,请参见[安装](/zh-cn/docs/install/)。然后在任意项目目录中启动 Herdr:
+
+```bash
+herdr
+```
+
+Herdr 会启动或连接到你的默认后台会话。你不需要管理 socket。即使分离,智能体也会继续运行。
+
+## 创建工作区
+
+当会话中没有工作区时,Herdr 会自动打开一个。工作区是项目级别的容器,容纳标签页、窗格和智能体。给每个活跃项目一个独立的工作区,这样侧边栏里的智能体状态才清晰可读。
+
+## 使用鼠标
+
+Herdr 是鼠标原生的,所以从点击开始。点击窗格、标签页、工作区和智能体来聚焦它们。拖动分割边框来调整大小。右键打开上下文菜单,包括分割窗格和创建标签页。拖选文本即可复制到剪贴板;双击一个词直接复制它。复制不需要 Ctrl+C。
+
+当终端把带修饰键的点击传给 Herdr 时,Ctrl+点击可以打开窗格内的链接。这对 OSC 8 超链接和可见的 `http://` 或 `https://` URL 有效。在 macOS 上,鼠标捕获开启时,请用 Ctrl+点击来触发 Herdr 处理的窗格链接;Cmd+点击只能通过终端原生的绕过路径使用,比如 Shift+Cmd+点击或 `ui.mouse_capture = false`。
+
+如果配置了 `ui.right_click_passthrough_modifier`,该修饰键加右键会把右键点击、按住和拖动手势发送给启用鼠标上报的窗格应用。
+
+## 运行智能体
+
+在窗格里启动你的编程智能体:
+
+```bash
+claude
+```
+
+也可以是 `codex`、`pi`、`opencode` 或任何其他[受支持的智能体](/zh-cn/docs/agents/)。Herdr 会自动检测。侧边栏会显示每个智能体处于 `working`、`blocked`、`done` 还是 `idle` — 并且跨所有工作区显示,所以你总能知道哪个项目需要你。
+
+## 键盘操作
+
+键盘操作是可选的;鼠标可以完成一切。按 `ctrl+b` 进入前缀模式,然后按一个动作键。
+
+常用动作:
+
+| 动作 | 按键 |
+| --- | --- |
+| 向右分割 | `prefix+v` |
+| 向下分割 | `prefix+minus` |
+| 新建标签页 | `prefix+c` |
+| 下一个 / 上一个标签页 | `prefix+n` / `prefix+p` |
+| 工作区导航 | `prefix+w` |
+| 新建工作区 | `prefix+shift+n` |
+| 分离客户端 | `prefix+q` |
+
+第一次接触前缀键的概念?[键盘](/zh-cn/docs/keyboard/)会解释它是什么、为什么终端复用器要用它,以及如何做到不用前缀键。在 Herdr 里按 `prefix+?` 查看所有生效的绑定,按 `prefix+[` 进入复制模式用键盘复制。
+
+## 分离与回来
+
+按 `prefix+q`,或者直接关掉终端窗口。Herdr 服务器和所有智能体会继续运行。再次运行 `herdr` 即可重新连接到同一个会话。
+
+要真正结束会话并停止其中的窗格:
+
+```bash
+herdr server stop
+```
+
+## 接下来
+
+- [核心概念](/zh-cn/docs/concepts/) — 两分钟了解工作区、标签页、窗格和智能体模型。
+- [使用 Herdr 的工作方式](/zh-cn/docs/how-to-work/) — 本地、SSH、手机和 `herdr --remote` 工作流。
+- [智能体](/zh-cn/docs/agents/) — 受支持的智能体、检测,以及提升状态准确度的集成。
+- [配置](/zh-cn/docs/configuration/) — 按键绑定、主题、通知,以及其他一切。
diff --git a/website/src/content/docs/zh-cn/session-state.mdx b/website/src/content/docs/zh-cn/session-state.mdx
new file mode 100644
index 00000000..2b41d038
--- /dev/null
+++ b/website/src/content/docs/zh-cn/session-state.mdx
@@ -0,0 +1,104 @@
+---
+title: 会话状态与恢复
+description: 理解 Herdr 保持哪些实时状态、重启后恢复什么、从历史回放什么、通过智能体集成恢复什么会话,以及更新时如何交接。
+---
+
+Herdr 有多条状态路径,它们解决的是不同的问题。
+
+## 什么能保留下来
+
+| 场景 | 进程继续运行 | 布局恢复 | 最近的屏幕内容恢复 | 智能体对话恢复 |
+| --- | --- | --- | --- | --- |
+| 分离并重新连接 | 是 | 是 | 是,来自实时终端 | 是,因为进程从未停止 |
+| 服务器重启 | 否 | 是 | 仅在开启窗格屏幕历史时 | 仅在有智能体原生会话恢复时 |
+| 不带 `--handoff` 的更新 | 兼容的服务器继续运行;需要重启的服务器可能要停止/重启 | 重启后恢复 | 仅在开启窗格屏幕历史时 | 仅在有智能体原生会话恢复时 |
+| 带 `--handoff` 的更新 | 对受支持的运行中服务器尽力而为 | 是 | 是,交接成功时来自实时终端 | 是,交接成功时进程保持运行 |
+
+下面的小节逐一解释这些路径。
+
+## 实时持久化
+
+普通分离会让 Herdr 服务器继续运行。窗格、shell、智能体、服务器、测试和命令进程都在该服务器中继续运行。
+
+用 `ctrl+b q` 分离客户端。之后重新连接:
+
+```bash
+herdr
+```
+
+这是最强的持久化路径,因为原始进程从未停止。
+
+## 快照恢复
+
+如果 Herdr 服务器停止后再启动,原来的窗格进程已经不在了。Herdr 会恢复保存的会话形态: 工作区、标签页、窗格、cwd、布局和焦点。
+
+快照恢复不会保留运行中的 shell、服务器、测试或任意进程。无法使用更强恢复路径的窗格,会在各自保存的目录中作为新 shell 回来。
+
+## 窗格屏幕历史回放
+
+窗格屏幕历史在服务器完全重启后恢复最近的终端内容。它恢复的是 Herdr 能展示的内容,而不是原来的进程。
+
+它默认关闭,因为窗格输出可能包含密钥、令牌、提示词和命令输出。可以在 Settings > Experiments > pane screen history 中开启,或者:
+
+```toml
+[experimental]
+pane_history = true
+```
+
+开启后,Herdr 把保存的窗格历史存放在 `session.json` 旁边的 `session-history.json` 中。请像对待终端历史一样对待 Herdr 的配置/会话目录。
+
+## 智能体原生会话恢复
+
+一些智能体可以恢复它们自己的对话会话。Herdr 可以使用官方集成上报的会话引用,在 Herdr 服务器重启后重新启动受支持的智能体窗格。
+
+这默认开启。关闭方法:
+
+```toml
+[session]
+resume_agents_on_restore = false
+```
+
+Herdr 只会恢复那些通过当前官方 Herdr 集成上报了原生会话引用的窗格。
+
+当客户端连接并提供终端尺寸和主题上下文后,Herdr 会跨工作区和标签页恢复符合条件的智能体窗格,不需要等每个窗格被聚焦。
+
+智能体原生会话恢复需要以下版本或更新的 Herdr 集成:
+
+| 智能体 | 最低 Herdr 集成版本 | 恢复命令 |
+| --- | --- | --- |
+| Pi | `2` | `pi --session <path-or-id>` |
+| OMP | `3` | `omp --resume=<path-or-id>` |
+| Claude Code | `6` | `claude --resume <id>` |
+| Codex | `5` | `codex resume <id>` |
+| Cursor Agent CLI | `1` | `cursor-agent --resume <id>` |
+| GitHub Copilot CLI | `2` | `copilot --resume=<id>` |
+| Devin CLI | `2` | `devin --resume <id>` |
+| Droid | `2` | `droid --resume <id>` |
+| Kimi Code CLI | `3` | `kimi --session <id>` |
+| Qoder CLI | `2` | `qodercli --resume <id>` |
+| OpenCode | `5` | `opencode --session <id>` |
+| Kilo Code CLI | `1` | `kilo --session <id>` |
+| Hermes Agent | `2` | `hermes --resume <id>` |
+
+运行 `herdr integration status` 查看已安装的集成版本。用 `herdr integration install <agent>` 重新安装过期的集成。
+
+不受支持、缺失、无效、重复或过期的会话引用,会在保存的窗格目录中作为普通 shell 恢复。
+
+如果某个窗格适用智能体原生会话恢复,Herdr 会对该窗格恢复智能体会话,而不是回放保存的窗格历史。
+
+## 实时交接
+
+实时交接用于需要替换运行中 Herdr 服务器的更新和远程连接流程。它请求旧服务器把实时窗格转移给新服务器,让窗格进程跨服务器替换继续运行。
+
+这与快照恢复、窗格历史回放和智能体原生会话恢复不同。交接尝试让当前进程活下去,其他路径则是在旧服务器已经停止之后重建状态。
+
+实时交接是实验性功能,需要主动开启:
+
+```bash
+herdr update --handoff
+herdr --remote workbox --handoff
+```
+
+普通的 `herdr update` 和普通的 `herdr --remote workbox` 默认使用常规的重启/停止流程。
+
+`herdr update --handoff` 只适用于由 Herdr 自带更新器管理的安装。Homebrew、mise 和 Nix 安装通过各自的包管理器更新,因此那些安装中 `herdr update` 被禁用,无法执行实时交接。
diff --git a/website/src/content/docs/zh-cn/socket-api.mdx b/website/src/content/docs/zh-cn/socket-api.mdx
new file mode 100644
index 00000000..3a5320b8
--- /dev/null
+++ b/website/src/content/docs/zh-cn/socket-api.mdx
@@ -0,0 +1,609 @@
+---
+title: Socket API
+description: 从脚本、工具和编程智能体控制运行中的 Herdr 服务器。
+---
+
+Herdr 为需要检查或控制运行中会话的脚本和智能体提供了一个本地 socket API。
+
+大多数自动化应从 CLI 包装命令开始。只有在需要直接的请求/响应控制或长期事件订阅时,才使用原始 socket API。
+
+## 选择集成层
+
+| 层 | 用途 |
+| --- | --- |
+| 智能体技能 | 教编程智能体如何在窗格内使用 Herdr。 |
+| CLI 包装 | Shell 脚本、简单编排和人工调试。 |
+| 原始 socket API | 自定义工具、协议客户端和事件订阅者。 |
+
+这些层共享同一套控制面。
+
+## 你能控制什么
+
+socket API 可以:
+
+- 创建、列出、聚焦、重命名和关闭工作区
+- 创建、列出、聚焦、重命名和关闭标签页
+- 列出、检查、分割、交换、聚焦、调整、重命名、读取、关闭窗格并向其发送输入
+- 通过 CLI 辅助命令列出、检查、读取、发送、重命名、聚焦、启动和附加智能体
+- 从钩子和插件上报自定义智能体状态
+- 订阅事件并等待输出或状态变化
+- 安装和卸载内置集成
+- 停止服务器并重载配置
+
+## CLI 示例
+
+创建工作区:
+
+```bash
+herdr workspace create --cwd ~/project --label api
+```
+
+创建标签页:
+
+```bash
+herdr tab create --label logs
+```
+
+分割窗格并运行命令:
+
+```bash
+herdr pane split w1:p1 --direction right
+herdr pane run w1:p2 "npm test"
+```
+
+检查并重排窗格:
+
+```bash
+herdr pane layout --current
+herdr pane neighbor --direction right --current
+herdr pane resize --direction right --amount 0.1 --current
+herdr pane swap --direction right --current
+herdr pane zoom --on --current
+herdr pane split w1:p1 --direction right --ratio 0.333
+```
+
+等待智能体:
+
+```bash
+herdr wait agent-status w1:p1 --status done
+```
+
+读取窗格输出:
+
+```bash
+herdr pane read w1:p2 --source recent --lines 50
+```
+
+## 原始方法
+
+原始 socket 方法名使用点号记法:
+
+| 领域 | 方法 |
+| --- | --- |
+| 服务器 | `ping`、`server.stop`、`server.reload_config`、`server.agent_manifests`、`server.reload_agent_manifests` |
+| 通知 | `notification.show` |
+| 客户端 | `client.window_title.set`、`client.window_title.clear` |
+| 工作区 | `workspace.create`、`workspace.list`、`workspace.get`、`workspace.focus`、`workspace.rename`、`workspace.close` |
+| Worktree | `worktree.list`、`worktree.create`、`worktree.open`、`worktree.remove` |
+| 标签页 | `tab.create`、`tab.list`、`tab.get`、`tab.focus`、`tab.rename`、`tab.close` |
+| 窗格 | `pane.split`、`pane.swap`、`pane.move`、`pane.zoom`、`pane.layout`、`pane.process_info`、`pane.neighbor`、`pane.edges`、`pane.focus_direction`、`pane.resize`、`pane.list`、`pane.current`、`pane.get`、`pane.rename`、`pane.send_text`、`pane.send_keys`、`pane.send_input`、`pane.read`、`pane.report_agent`、`pane.report_agent_session`、`pane.report_metadata`、`pane.clear_agent_authority`、`pane.release_agent`、`pane.close`、`pane.wait_for_output` |
+| 布局 | `layout.export`、`layout.apply` |
+| 智能体 | `agent.list`、`agent.get`、`agent.read`、`agent.explain`、`agent.send`、`agent.rename`、`agent.focus`、`agent.start` |
+| 事件 | `events.subscribe`、`events.wait` |
+| 集成 | `integration.install`、`integration.uninstall` |
+| 插件 | `plugin.link`、`plugin.list`、`plugin.unlink`、`plugin.enable`、`plugin.disable`、`plugin.action.list`、`plugin.action.invoke`、`plugin.log.list`、`plugin.pane.open`、`plugin.pane.focus`、`plugin.pane.close` |
+
+一些 CLI 命令是这些方法的便捷包装。比如 `herdr agent wait` 先解析智能体目标,然后订阅窗格智能体状态事件。
+
+窗格控制方法使用 `w1:p1` 这类公开窗格 id。schema 中 `pane_id` 可选的方法,在省略它时使用服务器当前聚焦的活动窗格。`pane.move` 总是要求来源 `pane_id`。
+
+`pane.send_keys` 和 `pane.send_input.keys` 接受 Herdr 组合键字符串: 普通可打印键、`enter` 和 `esc` 这类特殊键、`ctrl+h`、`control+j`、`alt+x`、`shift+tab` 这类修饰组合键、`f1` 这类功能键,以及 `minus` 和 `plus` 这类命名标点。它们不接受 `prefix+` 绑定字符串。
+
+```json
+{"id":"req_current","method":"pane.current","params":{"caller_pane_id":"w1:p1"}}
+{"id":"req_layout","method":"pane.layout","params":{"pane_id":"w1:p1"}}
+{"id":"req_neighbor","method":"pane.neighbor","params":{"pane_id":"w1:p1","direction":"right"}}
+{"id":"req_edges","method":"pane.edges","params":{"pane_id":"w1:p1"}}
+{"id":"req_focus","method":"pane.focus_direction","params":{"direction":"right"}}
+{"id":"req_resize","method":"pane.resize","params":{"pane_id":"w1:p1","direction":"right","amount":0.1}}
+{"id":"req_zoom","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"toggle"}}
+{"id":"req_split","method":"pane.split","params":{"direction":"right","ratio":0.333,"env":{"HERDR_ROLE":"tests"}}}
+{"id":"req_process","method":"pane.process_info","params":{"pane_id":"w1:p1"}}
+```
+
+`pane.current` 返回单个 `PaneInfo`。带有 `caller_pane_id` 时,Herdr 返回那个窗格。省略时,Herdr 返回当前聚焦的活动窗格。
+
+`pane.layout` 返回标签页布局快照,包含 `workspace_id`、`tab_id`、`zoomed`、外层 `area`、`focused_pane_id`、窗格矩形和分割矩形/比例。`pane.neighbor` 和 `pane.edges` 也包含同一份布局快照,让客户端不需要私有布局状态就能做出下一步决策。
+
+`pane.process_info` 返回窗格的 shell pid、可用时的前台进程组 id,以及平台暴露时带有 pid、名称、argv/cmdline 和 cwd 的前台进程。
+
+`layout.export` 返回可移植的标签页布局树。省略 `tab_id` 和 `pane_id` 导出活动标签页,传 `tab_id` 导出该标签页,或传 `pane_id` 导出包含该窗格的标签页。
+
+```json
+{"id":"req_export","method":"layout.export","params":{"tab_id":"w1:t1"}}
+```
+
+响应包含 `workspace_id`、`tab_id`、`zoomed`、`focused_pane_id` 和 `root`。`root` 是由 `pane` 和 `split` 节点组成的 BSP 树。窗格节点可以包含 `pane_id`、`label`、`cwd` 和 argv `command`。分割节点使用 `direction` (`right` 或 `down`)、`ratio`、`first` 和 `second`。
+
+`layout.apply` 从声明式的树创建一个新标签页。提供 `tab_id` 时,Herdr 先创建替代标签页,再关闭旧标签页。它会恢复结构、标签、cwd、env 和可选的 argv 命令;不会保留活跃的 PTY、回滚内容或运行中的进程。
+
+```json
+{
+ "id": "req_apply",
+ "method": "layout.apply",
+ "params": {
+ "workspace_id": "wabc",
+ "tab_label": "dev",
+ "focus": true,
+ "root": {
+ "type": "split",
+ "direction": "right",
+ "ratio": 0.65,
+ "first": {
+ "type": "pane",
+ "label": "editor",
+ "cwd": "/repo"
+ },
+ "second": {
+ "type": "pane",
+ "label": "tests",
+ "cwd": "/repo",
+ "command": ["sh", "-c", "just test"],
+ "env": { "HERDR_ROLE": "tests" }
+ }
+ }
+ }
+}
+```
+
+启动进程的方法接受一个 `env` 对象。Herdr 只把这些键值对应用到新启动的进程。Herdr 还向受管窗格进程注入 `HERDR_SOCKET_PATH`、`HERDR_ENV=1`、`HERDR_WORKSPACE_ID`、`HERDR_TAB_ID` 和 `HERDR_PANE_ID`。与调用方提供的环境变量冲突时,Herdr 管理的变量保持权威。
+
+`pane.swap` 支持按方向和显式两种形式:
+
+```json
+{"id":"req_swap_dir","method":"pane.swap","params":{"pane_id":"w1:p1","direction":"right"}}
+{"id":"req_swap_explicit","method":"pane.swap","params":{"source_pane_id":"w1:p1","target_pane_id":"w1:p2"}}
+```
+
+交换仅限同一标签页。它保留分割形状、分割比例、窗格 id 和运行中的进程。响应是 `type: "pane_swap"`,带 `changed`、可选的 `reason`、`source_pane_id`、可选的 `target_pane_id`、`focused_pane_id` 和 `layout`。reason 的取值有 `no_neighbor`、`same_pane`、`not_found` 和 `cross_tab`。标签页处于缩放状态时,交换保持缩放,并修改隐藏的整页布局。
+
+`pane.move` 把运行中的窗格移动到另一个标签页、新标签页或新工作区:
+
+```json
+{"id":"req_move_tab","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"tab","tab_id":"w1:t2","target_pane_id":"w1:p3","split":"right","ratio":0.5},"focus":true}}
+{"id":"req_move_new_tab","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"new_tab","workspace_id":"w1","label":"logs"},"focus":true}}
+{"id":"req_move_new_workspace","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"new_workspace","label":"logs","tab_label":"main"},"focus":true}}
+```
+
+移动到已有标签页需要 `split: "right" | "down"`。`target_pane_id` 可选,默认是目标标签页的聚焦窗格。同一标签页内的布局变化仍然用 `pane.swap`;移动到来源标签页返回 `changed: false` 和 `reason: "same_tab"`。涉及缩放状态的来源或目标标签页的移动返回 `changed: false` 和 `reason: "zoomed_tab"`。
+
+响应是 `type: "pane_move"`,带 `changed`、可选的 `reason`、`previous_pane_id`、`previous_workspace_id`、`previous_tab_id`、被移动的 `pane`、可选的 `source_layout`、`target_layout`、可选的新建工作区或标签页记录、可选的已关闭工作区或标签页 id,以及 `focused_pane_id`。跨工作区移动保持内部窗格和终端存活,但在目标工作区分配新的公开窗格 id。订阅者可以监听 `pane.moved`;Herdr 不会为被移动的终端进程发出假的窗格关闭/创建事件。
+
+`pane.zoom` 切换、启用或禁用目标窗格所在标签页的缩放:
+
+```json
+{"id":"req_zoom_toggle","method":"pane.zoom","params":{"pane_id":"w1:p1"}}
+{"id":"req_zoom_on","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"on"}}
+{"id":"req_zoom_off","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"off"}}
+```
+
+省略 `pane_id` 时,目标是服务器当前聚焦的活动窗格。响应是 `type: "pane_zoom"`,带 `changed`、`zoom_changed`、`focus_changed`、可选的 `reason`、`pane_id`、`focused_pane_id`、`zoomed` 和 `layout`。缩放状态或焦点任一发生变化时,`changed` 为 true。reason 的取值有 `single_pane`、`already_zoomed` 和 `already_unzoomed`。
+
+`notification.show` 的 CLI 包装是:
+
+```bash
+herdr notification show "build failed" --body "api workspace" --position top-left --sound request
+```
+
+通过配置的 toast 投递方式显示用户通知:
+
+```json
+{"id":"req_notify","method":"notification.show","params":{"title":"build failed","body":"api workspace","position":"top-left","sound":"request"}}
+```
+
+`title` 必填,并且在移除控制字符和重复空白后必须仍有可见文本。`body` 可选。Herdr 把换行、制表符、回车和重复空白折叠为空格,然后把通知文本截断: `title` 80 个字符,`body` 240 个字符。净化后为空的 `title` 返回 `invalid_params`。`position` 可选,只在 `ui.toast.delivery = "herdr"` 时生效;桌面位置相对于完整的 Herdr 画面,省略时使用 `ui.toast.herdr.position`。terminal、system 和 off 投递忽略 `position`。`sound` 可选,取值 `none`、`done` 或 `request`;默认 `none`,且只在通知实际显示时播放。
+
+响应会报告是否有内容被显示:
+
+```json
+{"id":"req_notify","result":{"type":"notification_show","shown":true,"reason":"shown"}}
+```
+
+可能的 reason 有 `shown`、`disabled`、`rate_limited`、`no_foreground_client` 和 `busy`。`disabled` 表示 `ui.toast.delivery = "off"`。`busy` 表示已有的应用内 toast 未被替换。terminal 和 system 投递是通过当前前台连接的 Herdr 客户端尽力而为的。
+
+设置或清除前台客户端的外层终端窗口标题:
+
+```json
+{"id":"req_title","method":"client.window_title.set","params":{"title":"herdr api"}}
+{"id":"req_title_clear","method":"client.window_title.clear","params":{}}
+```
+
+`client.window_title.clear` 恢复 Herdr 的默认标题。响应是 `type: "client_window_title"`,带 `changed` 和 `set`、`cleared` 或 `no_foreground_client` 之一的 reason。
+
+Worktree 方法把 Git 检出作为 Herdr 工作区管理。`worktree.create` 创建检出,并返回新的 `workspace`、`tab`、`root_pane` 和 `worktree` 记录。请求的分支已在本地存在时检出它;否则从请求的 base 或 `HEAD` 创建分支。`worktree.open` 打开已有检出,或返回已打开的工作区。`worktree.remove` 对关联的子工作区运行 `git worktree remove`,从不删除分支。
+
+从来源工作区创建 worktree:
+
+```json
+{"id":"req_1","method":"worktree.create","params":{"workspace_id":"w1","branch":"worktree/api","focus":false}}
+```
+
+打开已有检出:
+
+```json
+{"id":"req_2","method":"worktree.open","params":{"workspace_id":"w1","branch":"worktree/api","focus":true}}
+```
+
+移除关联的检出:
+
+```json
+{"id":"req_3","method":"worktree.remove","params":{"workspace_id":"2","force":false}}
+```
+
+`worktree.list`、`worktree.create` 和 `worktree.open` 中,`workspace_id` 和 `cwd` 最多用一个;两个都省略则使用活动工作区。`worktree.open` 中,`path` 和 `branch` 恰好用一个。原始 socket 的 `cwd` 和 `path` 值必须是绝对路径;CLI 在发送请求前会展开相对的 `--cwd` 和 `--path` 值。当工作区属于某个 Herdr worktree 组时,工作区响应包含可选的 `worktree` 来源信息。当已有工作区获得或改变 worktree 来源信息时,worktree 命令可能发出 `workspace.updated`。
+
+Worktree 命令也发出生命周期事件。`worktree.create` 发出 `workspace.created`、`tab.created`、`pane.created` 和 `worktree.created`。`worktree.open` 发出 `worktree.opened`,并在打开新的 Herdr 工作区时同时发出工作区/标签页/窗格创建事件。`worktree.remove` 发出 `worktree.removed`;如果关联的工作区仍然打开,还会发出 `workspace.closed`。
+
+## 插件 API
+
+插件 API 是面向可执行工作流工具的早期宿主面。插件是带 `herdr-plugin.toml` 清单的包。清单声明可分享的动作、事件钩子、终端窗格入口点和链接处理器。动作和窗格仅限清单声明;运行时动作注册和运行时 argv 窗格创建不在 v1 范围内。
+
+安装和链接的插件跨重启持久化。在 `plugin.link`、`plugin.unlink`、`plugin.enable` 和 `plugin.disable` 时,Herdr 在 `session.json` 旁写入一个 `plugins.json` 注册表文件。Herdr 不在运行时,`herdr plugin install` CLI 也写同一个注册表,然后启动时自动加载。启动时,Herdr 从原始路径重新读取每个清单;文件缺失或无法解析时,条目会带着 `warnings` 字段保留,`plugin.list` 会将其展示出来。
+
+事件钩子的 `on` 值在链接时会对照已知的 Herdr 事件名校验。无法识别的名称不算错误 — 链接仍会成功 — 但返回的插件信息会包含警告 (例如 `"unknown event 'worktree.craeted'"`)。检查 `plugin.link` 和 `plugin.list` 响应中的 `warnings` 字段。
+
+链接本地插件清单:
+
+```json
+{"id":"req_plugin_link","method":"plugin.link","params":{"path":"/path/to/plugin","enabled":true}}
+```
+
+`plugin.link` 也接受可选的 `source` 元数据。CLI 从 GitHub 安装时使用它,让 `plugin.list` 能显示来源、请求的 ref、解析的 commit 和托管检出路径:
+
+```json
+{"id":"req_plugin_link","method":"plugin.link","params":{"path":"/managed/plugin/herdr-plugin.toml","enabled":true,"source":{"kind":"github","owner":"ogulcancelik","repo":"herdr-plugin-examples","subdir":"worktree-bootstrap","requested_ref":"main","resolved_commit":"abc123","managed_path":"/data/plugins/github/<managed-checkout>","installed_unix_ms":1780000000000}}}
+```
+
+路径可以是包含 `herdr-plugin.toml` 的插件目录,或直接指向清单的路径。清单结构如下:
+
+```toml
+id = "example.worktree-bootstrap"
+name = "Worktree Bootstrap"
+version = "0.1.0"
+min_herdr_version = "0.7.0"
+description = "Prepare new worktrees"
+platforms = ["linux", "macos", "windows"]
+
+[[build]]
+command = ["bun", "install"]
+
+[[actions]]
+id = "bootstrap"
+title = "Bootstrap worktree"
+contexts = ["workspace"]
+command = ["bun", "run", "bootstrap.ts"]
+
+[[events]]
+on = "worktree.created"
+command = ["bun", "run", "bootstrap.ts"]
+
+[[panes]]
+id = "board"
+title = "Worktree board"
+placement = "overlay"
+command = ["bun", "run", "board.ts"]
+
+[[link_handlers]]
+id = "github-issue"
+title = "Open GitHub issue"
+pattern = "^https://github\\.com/[^/]+/[^/]+/(issues|pull)/[0-9]+$"
+action = "bootstrap"
+```
+
+`min_herdr_version` 是必填项。字段缺失、无效,或比运行中的 Herdr 二进制更新时,服务器拒绝链接插件。
+
+在顶层用你的插件支持的操作系统标识 (`linux`、`macos`、`windows`) 声明 `platforms`。本地开发允许省略 `platforms` — `plugin.link` 会成功,但响应包含警告。单个构建命令、动作、事件钩子、窗格和链接处理器可以声明自己的 `platforms` 来覆盖插件级列表;省略时从插件继承。调用有效 platforms 不包含当前操作系统的动作或打开这样的窗格,会返回 `platform_unsupported` 错误。
+
+列出、启用、禁用或取消链接插件:
+
+```json
+{"id":"req_plugin_list","method":"plugin.list","params":{}}
+{"id":"req_plugin_disable","method":"plugin.disable","params":{"plugin_id":"example.worktree-bootstrap"}}
+{"id":"req_plugin_enable","method":"plugin.enable","params":{"plugin_id":"example.worktree-bootstrap"}}
+{"id":"req_plugin_unlink","method":"plugin.unlink","params":{"plugin_id":"example.worktree-bootstrap"}}
+```
+
+动作从链接的清单解析。`plugin.action.list` 返回所有已安装插件的全部动作;传 `plugin_id` 过滤。
+
+```json
+{"id":"req_plugin_actions","method":"plugin.action.list","params":{}}
+{"id":"req_plugin_actions_filtered","method":"plugin.action.list","params":{"plugin_id":"example.worktree-bootstrap"}}
+```
+
+`plugin.action.list` 返回应用插件级继承后每个动作的有效 `platforms`。
+
+用限定 id 或裸动作 id 调用动作:
+
+```json
+{"id":"req_plugin_invoke","method":"plugin.action.invoke","params":{"action_id":"example.worktree-bootstrap.bootstrap","context":{"invocation_source":"keybinding"}}}
+```
+
+`plugin.action.invoke` 解析清单动作,启动清单命令,并返回 Herdr 构建的调用上下文和已启动命令的日志记录。缺失的上下文字段会从活动工作区、标签页、聚焦窗格、worktree 来源信息和请求 id 补全。调用被禁用插件的动作返回 `plugin_disabled` 错误。
+
+Herdr 注入 `HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ENV=1`、`HERDR_PLUGIN_ID`、`HERDR_PLUGIN_ROOT`、`HERDR_PLUGIN_CONFIG_DIR`、`HERDR_PLUGIN_STATE_DIR`、`HERDR_PLUGIN_CONTEXT_JSON`,以及可用的 `HERDR_WORKSPACE_ID`、`HERDR_TAB_ID` 和 `HERDR_PANE_ID` 值。动作命令还收到 `HERDR_PLUGIN_ACTION_ID`;事件钩子收到 `HERDR_PLUGIN_EVENT` 和 `HERDR_PLUGIN_EVENT_JSON`;窗格命令收到 `HERDR_PLUGIN_ENTRYPOINT_ID`。
+
+列出最近的动作和事件命令日志:
+
+```json
+{"id":"req_plugin_logs","method":"plugin.log.list","params":{"plugin_id":"example.worktree-bootstrap","limit":20}}
+```
+
+当 Herdr 发出匹配的事件名 (比如 `worktree.created`) 时,事件钩子为已启用的已安装插件运行。
+
+v1 没有 Herdr 管理的插件存储 API。`HERDR_PLUGIN_CONFIG_DIR` 和 `HERDR_PLUGIN_STATE_DIR` 只提供路径发现;文件、schema、迁移和清理归插件所有。
+
+打开托管终端 UI:
+
+```json
+{"id":"req_plugin_pane","method":"plugin.pane.open","params":{"plugin_id":"example.board","entrypoint":"board","placement":"zoomed","target_pane_id":"w1:p1","env":{"HERDR_ROLE":"board"},"focus":true}}
+```
+
+`plugin.pane.open` 要求已安装、已启用、平台兼容的插件,然后把请求的清单 `[[panes]]` 入口点作为 argv 支撑的终端窗格启动。清单窗格的 `placement` 默认为 `overlay`;请求的 `placement` 可以用 `overlay`、`split`、`tab` 或 `zoomed` 覆盖清单。覆盖层窗格针对活动窗格。分割和缩放窗格针对已有窗格;标签页窗格可以针对工作区。窗格打开后表现得像普通 Herdr 窗格,但 `plugin.pane.focus` 和 `plugin.pane.close` 只作用于通过插件 API 打开的窗格。focus 返回 `plugin_pane_focused`;close 返回 `plugin_pane_closed`。
+
+## Socket 传输
+
+Herdr 在本地 socket 上使用换行分隔的 JSON。在 Unix 上,那个 socket 是 Unix 域 socket。在 Windows 上,是命名管道。
+
+每行发送一个请求:
+
+```json
+{"id":"req_1","method":"ping","params":{}}
+```
+
+成功响应包含相同的 `id`:
+
+```json
+{"id":"req_1","result":{"type":"pong"}}
+```
+
+事件订阅在初始响应之后保持连接打开。
+
+## Socket 路径
+
+默认 socket 位于你的 Herdr 配置目录下。
+
+命名会话有各自独立的 socket:
+
+```text
+~/.config/herdr/herdr.sock
+~/.config/herdr/sessions/<name>/herdr.sock
+```
+
+解析顺序:
+
+1. 显式的 CLI `--session <name>`
+2. `HERDR_SOCKET_PATH`
+3. `HERDR_SESSION=<name>`
+4. 默认会话 socket
+
+`HERDR_SOCKET_PATH` 只用于底层覆盖。
+
+对插件来说,需要可移植的 Windows 行为时,优先调用 `HERDR_BIN_PATH` 和 CLI 包装命令。原始 socket 客户端要自己负责使用平台原生的本地 socket 形式。
+
+## 智能体状态上报
+
+集成用 `pane.report_agent` 上报智能体状态。
+
+```json
+{
+ "id": "req_1",
+ "method": "pane.report_agent",
+ "params": {
+ "pane_id": "w1:p1",
+ "source": "custom:docs",
+ "agent": "docs-bot",
+ "state": "working",
+ "message": "building docs",
+ "custom_status": "indexing"
+ }
+}
+```
+
+`state` 是语义性的。它影响等待、通知和汇总。
+
+`custom_status` 是视觉性的。它可以显示 `indexing` 这类简短的活动标签,而不改变语义行为。
+
+仅提供会话的官方集成用 `pane.report_agent_session` 上报原生会话引用。上报状态的集成仍然可以在 `pane.report_agent` 中包含原生会话引用。与状态无关的会话上报不影响等待、通知或汇总。
+
+```json
+{
+ "id": "req_2",
+ "method": "pane.report_agent_session",
+ "params": {
+ "pane_id": "w1:p1",
+ "source": "herdr:codex",
+ "agent": "codex",
+ "agent_session_id": "..."
+ }
+}
+```
+
+Herdr 存有原生会话引用时,`pane.get`、`pane.list`、`agent.get` 和 `agent.list` 暴露一个只读的 `agent_session` 对象:
+
+```json
+{
+ "agent_session": {
+ "source": "herdr:codex",
+ "agent": "codex",
+ "kind": "id",
+ "value": "..."
+ }
+}
+```
+
+没有存储原生会话引用时,该字段被省略。
+
+当 Herdr 能解析当前控制窗格 PTY 的进程的 cwd 时,`pane.get`、`pane.list`、`agent.get` 和 `agent.list` 也暴露 `foreground_cwd`。已有的 `cwd` 字段仍然是用于标签、follow-cwd 行为和恢复会话状态的窗格/工作区 cwd。
+
+当用户钩子想自定义展示、又不从 Herdr 集成接管生命周期状态时,使用 `pane.report_metadata`。
+
+```json
+{
+ "id": "req_2",
+ "method": "pane.report_metadata",
+ "params": {
+ "pane_id": "w1:p1",
+ "source": "user:claude-title",
+ "agent": "claude",
+ "title": "Refactor auth middleware",
+ "display_agent": "Claude: auth",
+ "custom_status": "refactor auth",
+ "state_labels": {
+ "working": "refactoring auth",
+ "idle": "ready",
+ "done": "review ready"
+ },
+ "ttl_ms": 3600000
+ }
+}
+```
+
+元数据上报只影响展示。有效的元数据可以覆盖窗格标题、显示的智能体名称、紧凑的活动标签和可见的状态标签。`working`、`blocked`、`idle`、等待、通知和汇总仍来自语义状态。原生会话恢复来自存储的官方会话引用。`agent` 是对权威智能体标签的可选守卫;`applies_to_source` 是对活动生命周期权威来源的可选守卫。用 `display_agent` 修改可见名称。`state_labels` 的键必须是 `idle`、`working`、`blocked`、`done` 或 `unknown`。用相同 `source` 搭配 `clear_custom_status: true` 这类清除字段,可以移除某一项展示覆盖。
+
+展示文本在存储前被规范化。Herdr 去掉首尾空白、移除控制字符、把 `custom_status` 截断到 32 个字符,把 `title`、`display_agent` 和每个状态标签截断到 80 个字符。规范化后为空的值被忽略。
+
+`source` 和 `applies_to_source` 是来源标识符。它们必须不超过 80 个字符,且只能包含 ASCII 字母、数字、冒号、点、下划线和连字符。
+
+短期元数据用 `ttl_ms`。取值必须在 `1` 到 `86400000` 毫秒之间。想让元数据保留到被替换、清除或窗格关闭时,省略 `ttl_ms`。TTL 过期时,Herdr 移除该来源的元数据,并在可见窗格展示发生变化时发出展示变化事件。
+
+钩子可能乱序发送更新时,使用 `seq`。对同一 `source`,序号小于等于最后接受序号的上报会被 API 接受,但被窗格状态忽略。
+
+## 事件订阅
+
+需要长期数据流时订阅事件:
+
+```json
+{
+ "id": "sub_1",
+ "method": "events.subscribe",
+ "params": {
+ "subscriptions": [
+ { "type": "pane.agent_status_changed", "pane_id": "w1:p1", "agent_status": "blocked" }
+ ]
+ }
+}
+```
+
+第一个响应确认订阅。之后的行是推送的事件。
+
+工作区事件订阅包括 `workspace.created`、`workspace.updated`、`workspace.renamed`、`workspace.closed` 和 `workspace.focused`。工作区事件描述 Herdr UI/运行时的生命周期。当工作区属于 worktree 组时,`workspace.created` 包含可选的 `workspace.worktree` 来源信息。在移除前 Herdr 仍能识别时,`workspace.closed` 包含最终的 `workspace` 快照。
+窗格事件订阅包括 `pane.created`、`pane.closed`、`pane.focused`、`pane.moved`、`pane.exited`、`pane.agent_detected`、`pane.output_matched` 和 `pane.agent_status_changed`。
+
+Worktree 事件订阅包括 `worktree.created`、`worktree.opened` 和 `worktree.removed`。Worktree 事件描述 Git 检出的生命周期。`worktree.created` 包含打开的 `workspace` 和创建的 `worktree`。`worktree.opened` 包含目标 `workspace`、打开的 `worktree` 和 `already_open`。`worktree.removed` 包含 `workspace_id`、被移除的 `worktree` 和 `forced`。
+
+生命周期事件用 `events.subscribe`。支持一次性等待时,专门的等待辅助命令会单独在文档中说明。
+
+## 读取窗格
+
+除非你在编写协议客户端,否则通过 CLI 使用 `pane.read`。
+
+```bash
+herdr pane read w1:p1 --source visible --lines 80
+herdr pane read w1:p1 --source recent --lines 120
+herdr pane read w1:p1 --source recent-unwrapped --lines 120
+herdr pane read w1:p1 --source detection
+```
+
+`recent-unwrapped` 对日志很有用,因为它忽略软折行。
+`detection` 返回智能体屏幕检测使用的底部缓冲区快照。
+
+## 等待状态
+
+用等待来协调智能体和脚本。
+
+```bash
+herdr wait agent-status w1:p1 --status done
+herdr wait agent-status w1:p1 --status blocked
+```
+
+智能体等待观察的是语义状态,不是任意命令的完成。
+
+## 响应结构
+
+成功响应长这样:
+
+```json
+{
+ "id": "req_1",
+ "result": {
+ "type": "pane_info",
+ "pane": {
+ "pane_id": "w1:p1",
+ "terminal_id": "term_abc123",
+ "workspace_id": "w1",
+ "tab_id": "w1:t1",
+ "focused": true,
+ "agent_status": "working",
+ "revision": 42
+ }
+ }
+}
+```
+
+`server.agent_manifests` 返回生效的智能体检测清单来源和远程更新诊断信息,不重载规则:
+
+```json
+{
+ "id": "req_1",
+ "result": {
+ "type": "agent_manifest_status",
+ "last_check_unix": 1781043522,
+ "last_result": "checked",
+ "manifests": [
+ {
+ "agent": "cursor",
+ "source": "/home/me/.config/herdr/agent-detection/cursor.toml",
+ "source_kind": "local override",
+ "active_version": "2026.06.10.1",
+ "cached_remote_version": "2026.06.10.1",
+ "local_override_shadowing_remote": true,
+ "remote_update_result": "current"
+ }
+ ]
+ }
+}
+```
+
+`last_check_unix`、`last_result`、`active_version`、`cached_remote_version`、`remote_update_result`、`remote_update_error`、`remote_last_checked_unix` 和 `warning` 这类字段在不可用时被省略。`server.reload_agent_manifests` 在重载内存中的规则缓存后,返回带相同 `manifests` 条目结构的 `agent_manifest_reload`。
+
+`agent.explain` 使用服务器生效的清单缓存,在运行中的服务器上评估目标窗格的检测快照:
+
+```json
+{
+ "id": "req_2",
+ "method": "agent.explain",
+ "params": { "target": "w1:p1" }
+}
+```
+
+响应包含与 `herdr agent explain --json` 打印的相同的 explain 对象,包括最终状态、清单来源和版本、匹配的规则、已评估规则的证据、跳过状态原因、idle 回退原因,以及当完整生命周期钩子权威使屏幕规则不再权威时的 `screen_detection_skip_reason`。
+
+客户端需要一个支持 `agent.explain` 的运行中服务器;升级 Herdr 后,请先重启或实时交接服务器,再依赖此方法。
+
+错误长这样:
+
+```json
+{
+ "id": "req_1",
+ "error": {
+ "code": "not_found",
+ "message": "pane not found"
+ }
+}
+```
+
+## 协议稳定性
+
+Herdr 有一个用于客户端/服务器兼容性的协议版本。协议变更会在考虑发布兼容性的前提下进行评审。
+
+在依赖新行为之前,用 `ping` 或 `herdr status` 检查服务器协议。对未知字段做宽容处理。
diff --git a/website/src/content/docs/zh-cn/windows-beta.mdx b/website/src/content/docs/zh-cn/windows-beta.mdx
new file mode 100644
index 00000000..e092451a
--- /dev/null
+++ b/website/src/content/docs/zh-cn/windows-beta.mdx
@@ -0,0 +1,100 @@
+---
+title: Windows 测试版
+description: Windows 原生支持的现状、受支持的工作流和已知限制。
+---
+
+Windows 原生支持是实验性的测试版。
+
+Windows 上的 Herdr 使用 ConPTY 和 Windows 的进程/运行时行为,而不是 Herdr 最初围绕构建的 Unix PTY 模型。有些 Herdr 功能可以干净地映射到 Windows,有些则不行。这个预览并不承诺每个 Linux/macOS 功能都会在 Windows 上得到完整支持。
+
+测试版的目标是从真实使用中学习: 安装成功率、窗格可靠性、智能体工作流、bug 数量、缺失的功能,以及 Windows 用户是否从 Herdr 获得了足够的价值。基于这些反馈,Windows 支持可能升级为稳定版,可能在成熟前保持仅预览,也可能在维护成本不合理时被缩减。
+
+用 PowerShell 安装 Windows 原生测试版构建:
+
+```powershell
+powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
+```
+
+Windows 测试版构建只通过预览通道发布。Windows 安装器默认使用预览通道,把 `channel = "preview"` 写入 Herdr 配置,将发布版本保存在 `%USERPROFILE%\.herdr\packages\standalone\releases` 下,让 `%LOCALAPPDATA%\Programs\Herdr\bin` 指向当前版本,并保留少量旧版本,以免运行中的进程阻塞更新。
+
+对于内部测试,`HERDR_MANIFEST_URL` 可以让安装器指向自定义清单,而不是 Herdr 的稳定或预览清单。
+
+## 测试版支持
+
+| 能力 | 状态 |
+| --- | --- |
+| 本地持久会话 | 测试版 |
+| 通过 ConPTY 的原生窗格 | 测试版 |
+| Windows Terminal / PowerShell 应用连接 | 测试版 |
+| `cmd.exe` 窗格 | 测试版 |
+| 启动 cwd 和工作区标签 | 测试版 |
+| 窗格启动 cwd | 测试版 |
+| 智能体命令发现 | 测试版 |
+| 智能体自报告集成 | 测试版 |
+| 智能体进程树检测 | 测试版 |
+| 从已知 cwd 检测 Git/worktree | 测试版 |
+| 插件 | 预览 |
+| 窗格屏幕历史 | 测试版 |
+| 嵌套启动覆盖 | 测试版 |
+
+Windows 智能体进程检测会扫描窗格 shell 的后代进程,识别直接运行的智能体和常见的命令包装器。它对 Codex、Claude 等智能体很有用,但和 Unix 前台进程组检测不是一回事。
+
+插件以预览状态支持在清单中声明 `windows` 平台。GitHub 安装、本地链接、构建命令、动作、事件和插件窗格在 Windows 上尽力而为。命令是 argv 命令,必须兼容 Windows;`npm`、`bun`、`node` 之类的 Node 包 shim 只要在 `PATH` 上就应该能用,而使用 `sh` 或 Bash 的 Unix 专用示例需要 Windows 专用的替代方案。平台过滤器会跳过不支持的构建命令,并对不支持的动作或窗格返回 `platform_unsupported`。
+
+## 部分支持
+
+| 能力 | 状态 |
+| --- | --- |
+| shell `cd` 之后的实时 cwd | 部分支持 |
+| 通过 shell 集成/OSC7 的实时 cwd | 测试版 |
+| 向智能体粘贴剪贴板图像 | 未验证 |
+| CJK 隐藏光标显示 | 测试版 |
+| Kitty graphics 渲染 | 未验证 |
+
+Herdr 可以在正确的目录中启动窗格,并能从你启动 Herdr 的目录创建初始工作区。启动之后 PowerShell 的目录变化则不同: Herdr 能检查的进程字段无法可靠跟踪后续的逻辑 `cd` 变化。实时 cwd 上报请使用 Herdr 集成或提示符 shell 集成。
+
+Windows Terminal 可能为特定智能体支持图像粘贴路径,但 Herdr 自己的剪贴板图像读取器尚未在 Windows 上接通。在 Windows 剪贴板桥实现并测试之前,请把 `alt+v` 图像粘贴视为未验证。远程剪贴板图像桥是独立功能,仍然绑定于 Unix/macOS 的 `herdr --remote`。
+
+Kitty graphics 仍是实验性功能,尚未宣称支持 Windows。除非你专门在 Windows Terminal 中测试图像渲染,否则保持 `experimental.kitty_graphics = false`。
+
+## 复制与粘贴
+
+Herdr 的窗格文本复制在 Windows 测试版上可用。在窗格内拖选文本即可通过 Herdr 复制。
+
+文本粘贴请在 Windows Terminal 中使用 `ctrl+shift+v`。多行文本粘贴是带括号的 (bracketed),因此 shell 和智能体提示符会把它作为一次粘贴接收,而不是逐行提交。按住 `shift` 再右键,可以使用外层终端的粘贴操作,而不把点击发给 Herdr。
+
+## Windows 测试版不支持
+
+| 能力 | 状态 |
+| --- | --- |
+| 直接终端附加 | 不支持 |
+| Windows 二进制的 `herdr --remote` | 不支持 |
+| 实时服务器交接 | 不支持 |
+| Unix 文件描述符交接 | 不支持 |
+| Unix 前台进程组 | 不支持 |
+| 远程剪贴板图像桥 | 不支持 |
+| 前缀输入法切换 | 不支持 |
+| 签名二进制 / 规避 SmartScreen | 不支持 |
+
+在 Windows 上进行远程工作,请 SSH 到服务器并在那里运行 `herdr`:
+
+```powershell
+ssh you@server
+herdr
+```
+
+这种模式下 Herdr 运行在远程主机上。Windows 原生的 `herdr --remote` 不在测试版范围内。
+
+Windows 更新通过 Windows 安装器进行,并更新带版本号的安装联接点。更新后请重启运行中的 Herdr 会话。实时交接仅限 Unix。
+
+## 报告 Windows 测试版问题
+
+请包含:
+
+- Herdr 版本。
+- Windows 版本。
+- 终端应用。
+- Shell,比如 PowerShell 或 cmd。
+- 是否使用了命名的 `HERDR_SESSION`。
+- 相关的 Herdr 日志。
+- 精确的复现步骤。