1 files changed, 62 insertions, 0 deletions
diff --git a/website/src/content/docs/ja/troubleshooting.mdx b/website/src/content/docs/ja/troubleshooting.mdx
new file mode 100644
index 00000000..c1eca500
--- /dev/null
+++ b/website/src/content/docs/ja/troubleshooting.mdx
@@ -0,0 +1,62 @@
+---
+title: トラブルシューティング
+description: インストール、ターミナル入力、セッション、キーバインド、リモート接続の一般的な問題を診断します。
+---
+
+まずバージョンとセッション状態を確認します:
+
+```bash
+herdr -V
+herdr status
+```
+
+OS、外側のターミナル名とバージョン、ローカルまたはリモートのどちらか、tmux を使用しているかも記録してください。
+
+## Enter、Tab、Backspace が 2 回入力される
+
+古いターミナルでは、アプリケーションが Kitty キーボードイベント報告を有効にすると、Enter、Tab、Backspace のリリースをプレスと同じバイトとして送ることがあります。送信後は Herdr から重複したバイトを区別できません。
+
+上流の修正を含むバージョンへ外側のターミナルを更新してください:
+
+| ターミナル | 修正済みの最小バージョン |
+| --- | --- |
+| kitty | 0.33.0 |
+| foot | 1.20.0 |
+| Alacritty | 0.15.0 |
+
+長期サポート版 Linux ディストリビューションの古いターミナルパッケージで特に発生します。確認済みの境界キャプチャと上流参照は [Herdr issue #1116](https://github.com/ogulcancelik/herdr/issues/1116) を参照してください。現在のターミナルでも発生する場合は、正確なバージョンと Herdr の外でも発生するかを報告してください。
+
+## Herdr を更新したのに実行中のセッションが古い
+
+バイナリを更新しても、互換性のある実行中サーバーは自動で置き換わらないことがあります。`herdr status` を確認してください。更新済みサーバーを起動するには、セッションを停止して Herdr を再起動します:
+
+```bash
+herdr server stop
+herdr
+```
+
+サーバーを停止するとペインのプロセスも終了します。名前付きセッションでは `herdr session stop <name>` を使います。更新機能、パッケージマネージャー、ライブハンドオフについては[インストール](/ja/docs/install/#update)を参照してください。
+
+## `herdr` コマンドが見つからない
+
+ターミナルを再起動して環境を読み込み直し、Herdr のインストール先が `PATH` に含まれていることを確認してください。パッケージマネージャー経由のインストールは、そのパッケージマネージャーから更新して公開する必要があります。[インストール](/ja/docs/install/#verify)を参照してください。
+
+## 直接キーバインドが動作しない
+
+OS または外側のターミナルが Herdr に届く前にキーを処理している可能性があります。そのレイヤーでキーを解放するか、別のバインドを選んでください。既知の競合と安全なデフォルトは[キーボード](/ja/docs/keyboard/#going-prefix-free)を参照してください。
+
+## リモートアタッチで認証できない
+
+まず `ssh <host>` で通常の OpenSSH 接続が動作することを確認してください。非対話シェル、CI、モバイルターミナルでパスフレーズ付きキーを使う場合は、リモートアタッチの前にキーを `ssh-agent` へ読み込んでください。[永続化とリモートアクセス](/ja/docs/persistence-remote/#remote-attach-over-ssh)を参照してください。
+
+## 診断ログを探す
+
+Herdr のログはデフォルトで `~/.config/herdr/` にあります:
+
+```text
+herdr.log
+herdr-client.log
+herdr-server.log
+```
+
+詳細なログには `HERDR_LOG=herdr=debug` を設定します。問題を報告するときは現在のログとローテーション済みログを含めてください。[設定](/ja/docs/configuration/#logs)を参照してください。