docs: document macos keychain launch context

refs #966

3 files changed, 51 insertions, 0 deletions

diff --git a/docs/next/website/src/content/docs/ja/troubleshooting.mdx b/docs/next/website/src/content/docs/ja/troubleshooting.mdx
index 21320dd0..e5aa64c9 100644
--- a/docs/next/website/src/content/docs/ja/troubleshooting.mdx
+++ b/docs/next/website/src/content/docs/ja/troubleshooting.mdx
@@ -70,6 +70,23 @@ herdr
 
 サーバーを停止するとペインのプロセスも終了します。名前付きセッションでは `herdr session stop <name>` を使います。更新機能、パッケージマネージャー、ライブハンドオフについては[インストール](/ja/docs/install/#update)を参照してください。
 
+## macOS の Herdr 内で Keychain を使うツールが失敗する
+
+Herdr のペインからサーバーの起動コンテキストを確認します:
+
+```bash
+launchctl managername
+```
+
+`Background` と表示された場合は、サーバーを停止し、通常の GUI ターミナルから Herdr を再起動してください:
+
+```bash
+herdr server stop
+herdr
+```
+
+サーバーを停止するとペインのプロセスも終了します。Herdr のペインは長時間動作するサーバーの macOS 起動コンテキストを継承するため、SSH やバックグラウンドジョブから起動されたサーバーは対話型 Keychain サービスにアクセスできないことがあります。詳細は [Herdr issue #966](https://github.com/herdrdev/herdr/issues/966) を参照してください。
+
 ## `herdr` コマンドが見つからない
 
 ターミナルを再起動して環境を読み込み直し、Herdr のインストール先が `PATH` に含まれていることを確認してください。パッケージマネージャー経由のインストールは、そのパッケージマネージャーから更新して公開する必要があります。[インストール](/ja/docs/install/#verify)を参照してください。
diff --git a/docs/next/website/src/content/docs/troubleshooting.mdx b/docs/next/website/src/content/docs/troubleshooting.mdx
index 7ad2f786..4c889c32 100644
--- a/docs/next/website/src/content/docs/troubleshooting.mdx
+++ b/docs/next/website/src/content/docs/troubleshooting.mdx
@@ -70,6 +70,23 @@ herdr
 
 Stopping a server exits its pane processes. Named sessions use `herdr session stop <name>`. See [Install Herdr](/docs/install/#update) for updater, package-manager, and live-handoff behavior.
 
+## Keychain-backed tools fail inside Herdr on macOS
+
+Check the server launch context from a Herdr pane:
+
+```bash
+launchctl managername
+```
+
+If it prints `Background`, stop the server and start Herdr again from a normal GUI terminal:
+
+```bash
+herdr server stop
+herdr
+```
+
+Stopping the server exits its pane processes. Herdr panes inherit the long-lived server's macOS launch context, so a server started through SSH or a background job may not have access to interactive Keychain services. See [Herdr issue #966](https://github.com/herdrdev/herdr/issues/966) for details.
+
 ## The `herdr` command is not found
 
 Restart the terminal so it reloads its environment, then confirm the Herdr install directory is on `PATH`. For package-manager installs, use that package manager to update Herdr and expose it on `PATH`. See [Install Herdr](/docs/install/#verify).
diff --git a/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx b/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx
index caf5ed80..7aa864fb 100644
--- a/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx
+++ b/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx
@@ -70,6 +70,23 @@ herdr
 
 停止服务器会结束窗格进程。命名会话使用 `herdr session stop <name>`。更新器、软件包管理器和实时移交行为见[安装 Herdr](/zh-cn/docs/install/#update)。
 
+## macOS 上依赖钥匙串的工具仅在 Herdr 内失败
+
+在 Herdr 窗格中检查服务器的启动上下文:
+
+```bash
+launchctl managername
+```
+
+如果输出为 `Background`，请停止服务器，然后从普通 GUI 终端重新启动 Herdr:
+
+```bash
+herdr server stop
+herdr
+```
+
+停止服务器会结束窗格进程。Herdr 窗格会继承长期运行服务器的 macOS 启动上下文，因此通过 SSH 或后台任务启动的服务器可能无法访问交互式钥匙串服务。详情见 [Herdr issue #966](https://github.com/herdrdev/herdr/issues/966)。
+
 ## 找不到 `herdr` 命令
 
 重启终端以重新加载环境，然后确认 Herdr 安装目录位于 `PATH` 中。通过软件包管理器安装的 Herdr 必须通过该管理器更新并加入环境。见[安装 Herdr](/zh-cn/docs/install/#verify)。