From 39a923460f8f35bf3768c0c6a0cf971828da6048 Mon Sep 17 00:00:00 2001
From: pi-agent <pi-agent@local>
Date: Sun, 2 Aug 2026 16:41:28 +0800
Subject: [PATCH 1/2] docs: document remote-use keybindings for sessionizer
 flows

---
 README.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/README.md b/README.md
index a5c4627..8723d23 100644
--- a/README.md
+++ b/README.md
@@ -116,6 +116,18 @@ command = "sessionizer.worktree-open"
 description = "open worktree workspace"
 ```
 
+### Remote use (`herdr --remote`)
+
+When you attach to a remote Herdr server, the Sessionizer keybindings above are read from the **remote** server's config, but Herdr's remote client may resolve keybindings from the machine you launched it from instead. If `sessionizer.open` / `sessionizer.worktree-open` do nothing under `herdr --remote`, attach with the server's keybindings:
+
+```sh
+herdr --remote <target> --remote-keybindings server
+```
+
+Alternatively, add the same `prefix+f` / `prefix+up` bindings to the Herdr config on the machine that launches `herdr --remote`.
+
+> The plugin itself runs on the remote host — bun, fzf, and the plugin checkout must be present there. See [Requirements](#requirements) for the runtime prerequisites.
+
 ## Layout configuration
 
 When Sessionizer **creates** a new project or worktree workspace, it applies the layout from `config.toml`. Existing workspaces are only focused — the layout is not reapplied.

From 7737282cc16803609c0afced134e0eaebd193d00 Mon Sep 17 00:00:00 2001
From: pi-agent <pi-agent@local>
Date: Sun, 2 Aug 2026 16:44:24 +0800
Subject: [PATCH 2/2] docs: drop ineffective remote-binding alternative

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 8723d23..3d6b857 100644
--- a/README.md
+++ b/README.md
@@ -124,7 +124,7 @@ When you attach to a remote Herdr server, the Sessionizer keybindings above are
 herdr --remote <target> --remote-keybindings server
 ```
 
-Alternatively, add the same `prefix+f` / `prefix+up` bindings to the Herdr config on the machine that launches `herdr --remote`.
+Bindings added to the machine that launches `herdr --remote` do **not** trigger the plugin in a remote session — they must come from the remote server's keybindings.
 
 > The plugin itself runs on the remote host — bun, fzf, and the plugin checkout must be present there. See [Requirements](#requirements) for the runtime prerequisites.