Merge branch 'master' into osc7501

2026-11-06 00:06:18 +00:00 · 2026-10-14 14:03:38 +02:00
parent acb361bee7 6521382dbe
commit ccefa3f138
198 changed files with 26396 additions and 6185 deletions
@@ -2,6 +2,56 @@

 ## Unreleased

+## [0.9.4] - 2026-10-13
+
+### Added
+- `herdr plugin update` updates plugins installed from GitHub, all at once or by name. Running plugin panes keep working on their old files, and new runs pick up the update without a config reload. Locally linked plugins are left alone. (#4245, thanks @JJLiebig)
+- Windows notifications stay in Notification Center. Clicking one jumps to its pane and brings the terminal window forward. (#4773, #4803, thanks @JJLiebig)
+
+### Changed
+- An elevated Windows server now only accepts administrator clients by default. To let normal clients from the same account in, set `[server] allow_unelevated_clients = true` or start the server with `--allow-unelevated-clients`. Permission errors now say how to fix them, and sessions you can't reach show as unavailable instead of stopped. (#4717, #4769, #4777, #4779, thanks @JJLiebig)
+- On Linux and macOS, closing the shell that started Herdr no longer stops the server. Scripts that stopped Herdr with `SIGHUP` should use `herdr server stop` or `SIGTERM`. The server log now says why the server stopped. (#4920, #4965)
+- With mouse capture on, plugins that handle a link get first pick when you click it. Turn capture off to use your terminal's own link shortcuts, like Command-click on macOS. (#4874, #5064, thanks @JJLiebig)
+- Antigravity and Grok count as idle once they are back at their prompt, even if their own background tasks or subagents are still running. (#3530, #4735, #4959)
+- Ctrl+Shift+letter reaches plain shells as the Ctrl key, like in Alacritty and WezTerm. Super, Hyper and Meta shortcuts no longer type escape-code junk into apps that can't read them. (#4356, #5017)
+
+### Fixed
+- Restarting a Mac or shutting down Windows keeps your agents' sessions. Herdr saves before the system starts closing apps, so agents come back where they were. (#4414, #5013, #5057, #5092, thanks @JJLiebig)
+- Session saves are written to disk before they replace the old file, so a crash or power cut can't leave an unreadable save. (#5150, #5152, thanks @JJLiebig)
+- The server keeps running when the machine runs out of processes or threads, instead of taking every pane down with it. (#3324, #4958)
+- An out-of-range workspace number returns `workspace_not_found` instead of crashing the server. (#5096, #5171)
+- Suspending an agent with Ctrl+Z and bringing it back with `fg` keeps its name and saved conversation. (#1647, #4964)
+- Restoring a session stays responsive when a checkout's Git data is slow or missing. Worktree groups survive checkouts that are temporarily unavailable, and opening the same repository twice no longer nests one workspace inside the other. (#4926, #4736, #4945, #4770, #4772, thanks @minatoaquaMK2 and @JJLiebig)
+- Closing a workspace's only pane asks first, like closing its last tab already does. Turn this off with `ui.confirm_close = false`. (#5143, #5173)
+- Ctrl shortcuts like Ctrl+W work on non-Latin keyboard layouts such as Russian, Greek or Hebrew. Latin layouts and AltGr characters keep their normal meaning. (#1079, #4961)
+- Accent keys and AltGr shortcuts work on Windows. (#4688, #5021, thanks @JJLiebig)
+- Shift+Enter and other enhanced keys keep working after the outer terminal resets, for example after VS Code's Reload Window. (#4985, #5088)
+- Quick Escape taps work on macOS with WezTerm's Kitty keyboard mode. (#1266, #5089)
+- Kitty keyboard apps get key releases and F1, F2 and F4 correctly, and Backspace works when the terminal sends Ctrl+H for it. (#4184, #4403, #3244, #5017)
+- Keyboard and terminal color replies no longer leak stray characters into pane input, and a half-finished color reply no longer freezes typing. (#4856, #4025, #5052, #5017, #5087)
+- Fish no longer repeats prompt fragments while you resize a pane. The same problem with zsh and Powerlevel10k is still open, waiting on a Ghostty fix. (#3672, #4977)
+- Apps that ask for pixel mouse coordinates get them, and clicks land in the right place on terminals that only report cells. (#4750, #3675, #5017, #4971)
+- Turning off Kitty graphics makes panes stop advertising image support, so apps fall back to text. (#4978, #4979)
+- Typing shows up faster, especially in PowerShell. (#4884, #5149, thanks @JJLiebig)
+- Big sessions use less CPU on busy agents and idle shells, hidden panes use less memory, and Windows panes need fewer threads. (#4506, #5083, #4845, #4847, #4849, #4850, #4873, #5085, #5091, thanks @JJLiebig)
+- New workspaces, tabs and splits start their shell at the right size instead of borrowing another pane's size. (#4419, #4873)
+- Forwarded SSH agents are no longer contacted every second, which could eventually break SSH and Git authentication. (#4931, #4962)
+- Sidebar width, collapsed groups and agent sorting on remote machines survive reconnects. Switching workspaces quickly while changing machines no longer gets canceled. (#4364, #5019, #4536, #5061, thanks @minatoaquaMK2 and @JJLiebig)
+- The sidebar collapse button stays clickable when the agent list has a scrollbar. (#4692, #4734, thanks @minatoaquaMK2)
+- The welcome screen shows your configured prefix. (#4745, #4747, thanks @JJLiebig)
+- Ctrl+[ leaves workspace navigation. (#1431, #2340, thanks @qaz74107410)
+- Keybindings that use `+` survive config reloads, and `/` opens Go To search on layouts where it needs Shift. (#4960, #4963, #4983, #5090, thanks @minatoaquaMK2)
+- Pasting from WezTerm on Windows into remote panes no longer types encoded key data. Copying no longer adds duplicate clipboard history entries, and closing a pane no longer hangs on a pending Enter. (#4725, #4730, #4709, #4872, thanks @JJLiebig)
+- Windows shells started through Scoop or 32-bit wrappers keep their working directory in new tabs and after restarts. (#4472, #4749, #5062, thanks @JJLiebig)
+- Windows ARM64 machines can be used as remote hosts through the x64 build, on a best-effort basis. (#4752)
+- Codex reports finished turns through its integration when started with `--no-daemon`, its startup update screen shows as blocked, and Codex and Pi status is recognized in more cases. (#4507, #4811, #4756, #5174, thanks @JJLiebig)
+- Antigravity permission, question and workspace-trust dialogs show as blocked, and its thinking spinner shows as working. (#3871, #3419, #3530, #4959)
+- Hermes started through its Python installer is recognized, and installing or removing its integration keeps your YAML plugin list intact. (#4910, #4909, #4911, #4984, thanks @minatoaquaMK2)
+- On macOS, `pane run` and `agent start` refuse commands too long for a shell that is still starting, instead of silently cutting them off. (#4950, #4988, thanks @minatoaquaMK2)
+
+### Removed
+- The experimental `HERDR_WINDOWS_INPUT_BACKEND=crossterm` setting is gone. Windows always uses its native console input. (#5017)
+
 ## [0.9.3] - 2026-09-29

 This is a hotfix release for v0.9.2. See the v0.9.2 notes for the full feature release: https://github.com/herdrdev/herdr/releases/tag/v0.9.2
@@ -778,7 +778,7 @@ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"

 [[package]]
 name = "herdr"
-version = "0.9.3"
+version = "0.9.4"
 dependencies = [
 "base64",
 "bincode",
@@ -1,6 +1,6 @@
 [package]
 name = "herdr"
-version = "0.9.3"
+version = "0.9.4"
 edition = "2021"
 build = "build.rs"
 description = "terminal workspace manager for AI coding agents"
@@ -29,7 +29,7 @@ ghostty-vt = { path = "crates/ghostty-vt" }
 base64 = "0.22.1"
 bincode = { version = "2", features = ["serde"] }
 bytes = "1"
-clap = { version = "4.5", default-features = false, features = ["std", "help", "usage"] }
+clap = { version = "4.5", default-features = false, features = ["std", "help", "usage", "error-context", "string"] }
 clap_complete = "4.5"
 crossterm = "0.29"
 ctrlc = { version = "3", features = ["termination"] }
@@ -84,6 +84,7 @@ windows-sys = { version = "0.61.2", features = [
    "Win32_System_LibraryLoader",
    "Win32_System_Ole",
    "Win32_System_Pipes",
+    "Win32_System_Power",
    "Win32_System_Registry",
    "Win32_System_SystemInformation",
    "Win32_System_Threading",
@@ -1,7 +1,7 @@
 id = "claude"
-version = "2026.09.11.1"
+version = "2026.10.11.1"
 min_engine_version = 2
-updated_at = "2026-09-11T00:00:00Z"
+updated_at = "2026-10-11T00:00:00Z"
 aliases = ["claude-code"]

 [[rules]]
@@ -94,6 +94,18 @@ any = [
  ] },
 ]

+[[rules]]
+id = "live_blocked_form_named_session"
+state = "blocked"
+priority = 980
+region = "whole_recent"
+visible_blocker = true
+
+# Bind every control to the same footer, allowing wrapping between words.
+# After the name divider, accept only a counted task panel with marked rows
+# and optional pending overflow. Free-form activity can be newer output (#4573).
+regex = ['(?i)(?:^|\n)[ \t]*enter\s+to\s+(?:confirm|select\s+·\s+(?:(?:tab/arrow|arrow)\s+keys|arrows|↑/↓|↑↓)\s+to\s+navigate)\s+·\s+esc\s+to\s+cancel[ \t]*\n(?:[ \t]*\n)*[ \t]*─{3,}[^\n]*(?:\n(?:[ \t]*\n)*[ \t]+\d+ tasks? \(\d+ done, (?:\d+ in progress, )?\d+ open\)(?:\n[ \t]+[◻◼✔][ \t]+[^\n]+)+(?:\n[ \t]+…[ \t]+\+\d+[ \t]+pending)?)?(?:\n[ \t]*)*\z']
+
 [[rules]]
 id = "dynamic_workflow_prompt"
 state = "blocked"
@@ -1,7 +1,7 @@
 id = "codex"
-version = "2026.10.01.1"
+version = "2026.10.11.1"
 min_engine_version = 3
-updated_at = "2026-10-01T00:00:00Z"
+updated_at = "2026-10-11T00:00:00Z"

 [[rules]]
 id = "osc_title_blocked"
@@ -60,8 +60,19 @@ state = "blocked"
 priority = 950
 region = "bottom_non_empty_lines(20)"
 visible_blocker = true
-contains = ["Update available!", "Update now"]
-regex = ['Skip\s+until\s+next\s+version', 'Press enter to continue\s*\z']
+# Keep the legacy dialog; the shared picker (0.159+) has a different heading
+# and footer. Choices can scroll out of a short viewport, but both gates must
+# remain visible. The passive update history notice has neither picker footer.
+any = [
+  { all = [
+    { contains = ["Update available!", "Update now"] },
+    { regex = ['Skip\s+until\s+next\s+version', 'Press enter to continue\s*\z'] },
+  ] },
+  { all = [
+    { regex = ['(?m)^\s*Update\s+available\s+·'] },
+    { regex = ['enter\s+continue\s+·\s+esc\s+skip\s*\z'] },
+  ] },
+]

 [[rules]]
 id = "live_strong_blocker"
@@ -1,37 +1,68 @@
 {
  "schema_version": 1,
  "channel": "preview",
-  "base_version": "0.9.2",
-  "build_id": "2026-09-29-8e78f929d8f0",
-  "commit": "8e78f929d8f0306a5c68518969e90274c44cb1f0",
-  "built_at": "2026-09-29T18:25:31Z",
+  "base_version": "0.9.3",
+  "build_id": "2026-10-12-6d697e1e75ff",
+  "commit": "6d697e1e75ff1e94ebd5d176fcbf7a36545ac557",
+  "built_at": "2026-10-12T13:28:54Z",
  "protocol": 22,
  "endpoint_generation": 1,
-  "notes": "Preview build 2026-09-29-8e78f929d8f0\n\n[View changes](https://github.com/herdrdev/herdr/compare/v0.9.2...8e78f929d8f0306a5c68518969e90274c44cb1f0)",
+  "notes": "Preview build 2026-10-12-6d697e1e75ff\n\n[View changes](https://github.com/herdrdev/herdr/compare/v0.9.0...6d697e1e75ff1e94ebd5d176fcbf7a36545ac557)",
  "assets": {
    "linux-x86_64": {
-      "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-8e78f929d8f0/herdr-linux-x86_64",
-      "sha256": "6f3dffff0c9805e414ff9285c0a5ce8ff8bd1c0118383360048837baad8ad6f5"
+      "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-10-12-6d697e1e75ff/herdr-linux-x86_64",
+      "sha256": "ae95cf186ff3794de3ff10d6e9b883af2fc3a74576649c488c92b251f114f1b2"
    },
    "linux-aarch64": {
-      "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-8e78f929d8f0/herdr-linux-aarch64",
-      "sha256": "f26292297337d1b54dc9d1f01e473d4c95d572410577aac70534a69bb9123b91"
+      "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-10-12-6d697e1e75ff/herdr-linux-aarch64",
+      "sha256": "7bceb09df1a6a2d50ac0817f444968641f2864d108d88a027ab4a604ff3602d1"
    },
    "macos-x86_64": {
-      "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-8e78f929d8f0/herdr-macos-x86_64",
-      "sha256": "7cdf43b44cb4c0731a98932aeabe992e75781f4eead337bc52aa6889eff188ff"
+      "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-10-12-6d697e1e75ff/herdr-macos-x86_64",
+      "sha256": "9c39cb7f74c10e6e355b96cb66056c4e8d2f9040a557549892bc2496d865cfb1"
    },
    "macos-aarch64": {
-      "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-8e78f929d8f0/herdr-macos-aarch64",
-      "sha256": "7ebb310f974eaac7e45e9a46db470de11b24050dd929314757c952459bceaf3f"
+      "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-10-12-6d697e1e75ff/herdr-macos-aarch64",
+      "sha256": "ec72195c14f252db81fb850e153c19bebac4114ce4557c011c4a08aaf4ab6865"
    },
    "windows-x86_64": {
-      "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-8e78f929d8f0/herdr-windows-x86_64.zip",
-      "sha256": "bbebbd192fc6356228efdfb89ad1ce86813f3aff41ad48dbf5082fbe94e2485c",
+      "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-10-12-6d697e1e75ff/herdr-windows-x86_64.zip",
+      "sha256": "768764b8c0a5b2e1262d337465c9490556f8ab490742acda06bff9e6ee18ea25",
      "format": "zip"
    }
  },
  "builds": {
+    "2026-10-12-6d697e1e75ff": {
+      "base_version": "0.9.3",
+      "commit": "6d697e1e75ff1e94ebd5d176fcbf7a36545ac557",
+      "built_at": "2026-10-12T13:28:54Z",
+      "protocol": 22,
+      "endpoint_generation": 1,
+      "tag": "preview-2026-10-12-6d697e1e75ff",
+      "assets": {
+        "linux-x86_64": {
+          "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-10-12-6d697e1e75ff/herdr-linux-x86_64",
+          "sha256": "ae95cf186ff3794de3ff10d6e9b883af2fc3a74576649c488c92b251f114f1b2"
+        },
+        "linux-aarch64": {
+          "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-10-12-6d697e1e75ff/herdr-linux-aarch64",
+          "sha256": "7bceb09df1a6a2d50ac0817f444968641f2864d108d88a027ab4a604ff3602d1"
+        },
+        "macos-x86_64": {
+          "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-10-12-6d697e1e75ff/herdr-macos-x86_64",
+          "sha256": "9c39cb7f74c10e6e355b96cb66056c4e8d2f9040a557549892bc2496d865cfb1"
+        },
+        "macos-aarch64": {
+          "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-10-12-6d697e1e75ff/herdr-macos-aarch64",
+          "sha256": "ec72195c14f252db81fb850e153c19bebac4114ce4557c011c4a08aaf4ab6865"
+        },
+        "windows-x86_64": {
+          "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-10-12-6d697e1e75ff/herdr-windows-x86_64.zip",
+          "sha256": "768764b8c0a5b2e1262d337465c9490556f8ab490742acda06bff9e6ee18ea25",
+          "format": "zip"
+        }
+      }
+    },
    "2026-09-29-8e78f929d8f0": {
      "base_version": "0.9.2",
      "commit": "8e78f929d8f0306a5c68518969e90274c44cb1f0",
@@ -892,31 +923,6 @@
          "sha256": "8a6a211edfb853615a39da8a03344a686e9bb28ee07080a8d17b116c5b1dbf13"
        }
      }
-    },
-    "2026-06-05-1ce4213d9ebb": {
-      "base_version": "0.6.8",
-      "commit": "1ce4213d9ebb6149395743baa03e62baeaeeb10c",
-      "built_at": "2026-06-05T04:33:42Z",
-      "protocol": 12,
-      "tag": "preview-2026-06-05-1ce4213d9ebb",
-      "assets": {
-        "linux-x86_64": {
-          "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-06-05-1ce4213d9ebb/herdr-linux-x86_64",
-          "sha256": "130478ead15570df80d4b71f35efb28be9da51958c2da438e0f766e76c6859fc"
-        },
-        "linux-aarch64": {
-          "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-06-05-1ce4213d9ebb/herdr-linux-aarch64",
-          "sha256": "35bd06cf80afaab8ecac0b1f6dc3dd74775865f6a1d682575b33f7c3424c616b"
-        },
-        "macos-x86_64": {
-          "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-06-05-1ce4213d9ebb/herdr-macos-x86_64",
-          "sha256": "1279ce4e1c5a73b3725af4e288153b3597aa3133a156588ce4f7f22d6b8a88d4"
-        },
-        "macos-aarch64": {
-          "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-06-05-1ce4213d9ebb/herdr-macos-aarch64",
-          "sha256": "4bd46e2f4e3d76bf730b105fe11de53093c5b580b7e0a042359a887c5ac6aef0"
-        }
-      }
    }
  }
 }
@@ -2,6 +2,56 @@

 ## Unreleased

+## [0.9.4] - 2026-10-13
+
+### Added
+- `herdr plugin update` updates plugins installed from GitHub, all at once or by name. Running plugin panes keep working on their old files, and new runs pick up the update without a config reload. Locally linked plugins are left alone. (#4245, thanks @JJLiebig)
+- Windows notifications stay in Notification Center. Clicking one jumps to its pane and brings the terminal window forward. (#4773, #4803, thanks @JJLiebig)
+
+### Changed
+- An elevated Windows server now only accepts administrator clients by default. To let normal clients from the same account in, set `[server] allow_unelevated_clients = true` or start the server with `--allow-unelevated-clients`. Permission errors now say how to fix them, and sessions you can't reach show as unavailable instead of stopped. (#4717, #4769, #4777, #4779, thanks @JJLiebig)
+- On Linux and macOS, closing the shell that started Herdr no longer stops the server. Scripts that stopped Herdr with `SIGHUP` should use `herdr server stop` or `SIGTERM`. The server log now says why the server stopped. (#4920, #4965)
+- With mouse capture on, plugins that handle a link get first pick when you click it. Turn capture off to use your terminal's own link shortcuts, like Command-click on macOS. (#4874, #5064, thanks @JJLiebig)
+- Antigravity and Grok count as idle once they are back at their prompt, even if their own background tasks or subagents are still running. (#3530, #4735, #4959)
+- Ctrl+Shift+letter reaches plain shells as the Ctrl key, like in Alacritty and WezTerm. Super, Hyper and Meta shortcuts no longer type escape-code junk into apps that can't read them. (#4356, #5017)
+
+### Fixed
+- Restarting a Mac or shutting down Windows keeps your agents' sessions. Herdr saves before the system starts closing apps, so agents come back where they were. (#4414, #5013, #5057, #5092, thanks @JJLiebig)
+- Session saves are written to disk before they replace the old file, so a crash or power cut can't leave an unreadable save. (#5150, #5152, thanks @JJLiebig)
+- The server keeps running when the machine runs out of processes or threads, instead of taking every pane down with it. (#3324, #4958)
+- An out-of-range workspace number returns `workspace_not_found` instead of crashing the server. (#5096, #5171)
+- Suspending an agent with Ctrl+Z and bringing it back with `fg` keeps its name and saved conversation. (#1647, #4964)
+- Restoring a session stays responsive when a checkout's Git data is slow or missing. Worktree groups survive checkouts that are temporarily unavailable, and opening the same repository twice no longer nests one workspace inside the other. (#4926, #4736, #4945, #4770, #4772, thanks @minatoaquaMK2 and @JJLiebig)
+- Closing a workspace's only pane asks first, like closing its last tab already does. Turn this off with `ui.confirm_close = false`. (#5143, #5173)
+- Ctrl shortcuts like Ctrl+W work on non-Latin keyboard layouts such as Russian, Greek or Hebrew. Latin layouts and AltGr characters keep their normal meaning. (#1079, #4961)
+- Accent keys and AltGr shortcuts work on Windows. (#4688, #5021, thanks @JJLiebig)
+- Shift+Enter and other enhanced keys keep working after the outer terminal resets, for example after VS Code's Reload Window. (#4985, #5088)
+- Quick Escape taps work on macOS with WezTerm's Kitty keyboard mode. (#1266, #5089)
+- Kitty keyboard apps get key releases and F1, F2 and F4 correctly, and Backspace works when the terminal sends Ctrl+H for it. (#4184, #4403, #3244, #5017)
+- Keyboard and terminal color replies no longer leak stray characters into pane input, and a half-finished color reply no longer freezes typing. (#4856, #4025, #5052, #5017, #5087)
+- Fish no longer repeats prompt fragments while you resize a pane. The same problem with zsh and Powerlevel10k is still open, waiting on a Ghostty fix. (#3672, #4977)
+- Apps that ask for pixel mouse coordinates get them, and clicks land in the right place on terminals that only report cells. (#4750, #3675, #5017, #4971)
+- Turning off Kitty graphics makes panes stop advertising image support, so apps fall back to text. (#4978, #4979)
+- Typing shows up faster, especially in PowerShell. (#4884, #5149, thanks @JJLiebig)
+- Big sessions use less CPU on busy agents and idle shells, hidden panes use less memory, and Windows panes need fewer threads. (#4506, #5083, #4845, #4847, #4849, #4850, #4873, #5085, #5091, thanks @JJLiebig)
+- New workspaces, tabs and splits start their shell at the right size instead of borrowing another pane's size. (#4419, #4873)
+- Forwarded SSH agents are no longer contacted every second, which could eventually break SSH and Git authentication. (#4931, #4962)
+- Sidebar width, collapsed groups and agent sorting on remote machines survive reconnects. Switching workspaces quickly while changing machines no longer gets canceled. (#4364, #5019, #4536, #5061, thanks @minatoaquaMK2 and @JJLiebig)
+- The sidebar collapse button stays clickable when the agent list has a scrollbar. (#4692, #4734, thanks @minatoaquaMK2)
+- The welcome screen shows your configured prefix. (#4745, #4747, thanks @JJLiebig)
+- Ctrl+[ leaves workspace navigation. (#1431, #2340, thanks @qaz74107410)
+- Keybindings that use `+` survive config reloads, and `/` opens Go To search on layouts where it needs Shift. (#4960, #4963, #4983, #5090, thanks @minatoaquaMK2)
+- Pasting from WezTerm on Windows into remote panes no longer types encoded key data. Copying no longer adds duplicate clipboard history entries, and closing a pane no longer hangs on a pending Enter. (#4725, #4730, #4709, #4872, thanks @JJLiebig)
+- Windows shells started through Scoop or 32-bit wrappers keep their working directory in new tabs and after restarts. (#4472, #4749, #5062, thanks @JJLiebig)
+- Windows ARM64 machines can be used as remote hosts through the x64 build, on a best-effort basis. (#4752)
+- Codex reports finished turns through its integration when started with `--no-daemon`, its startup update screen shows as blocked, and Codex and Pi status is recognized in more cases. (#4507, #4811, #4756, #5174, thanks @JJLiebig)
+- Antigravity permission, question and workspace-trust dialogs show as blocked, and its thinking spinner shows as working. (#3871, #3419, #3530, #4959)
+- Hermes started through its Python installer is recognized, and installing or removing its integration keeps your YAML plugin list intact. (#4910, #4909, #4911, #4984, thanks @minatoaquaMK2)
+- On macOS, `pane run` and `agent start` refuse commands too long for a shell that is still starting, instead of silently cutting them off. (#4950, #4988, thanks @minatoaquaMK2)
+
+### Removed
+- The experimental `HERDR_WINDOWS_INPUT_BACKEND=crossterm` setting is gone. Windows always uses its native console input. (#5017)
+
 ## [0.9.3] - 2026-09-29

 This is a hotfix release for v0.9.2. See the v0.9.2 notes for the full feature release: https://github.com/herdrdev/herdr/releases/tag/v0.9.2
@@ -75,7 +75,11 @@ Some restricted Linux runtimes do not expose a terminal foreground process group

 Blocked detection is deliberately strict for screen-manifest agents. Herdr only marks `blocked` when the live bottom-buffer snapshot matches known visible approval, question, or permission UI. If no manifest rule matches for a known agent, Herdr falls back to `idle` and labels that fallback as `default_known_agent_idle_fallback` in explain output.

-This means unusual new agent prompts may initially show as `idle` instead of `blocked` until Herdr learns that screen shape. The misclassification affects only the visible status and waits. It should not make Herdr send input or take destructive action.
+Unusual new agent prompts may initially show as `idle` instead of `blocked` until Herdr learns that screen shape. Detection itself does not send input, but automation that trusts a mistaken idle state can type into an approval dialog. Inspect unexpected prompts before sending more input; idle status is not authorization to approve an action.
+
+Antigravity and Grok count as idle once they return to their prompt, even if background tasks, monitors, or subagents are still running. `agent wait` and `agent prompt --wait` observe the agent's state, not completion of those jobs.
+
+Suspending an agent with Ctrl+Z preserves its name, session reference, and hook authority while the exact process remains alive behind the shell or another non-agent command. Returning with `fg` keeps that identity. This does not cover another recognized agent taking over the foreground. A retained identity does not mean the agent can receive input while suspended; inspect the pane before prompting it.

 ## Detection manifests

@@ -7,6 +7,8 @@ Herdr’s CLI talks to the running server over the same local socket API used by

 Most commands print JSON responses for deterministic automation in scripts.

+API-backed commands use the same argument definitions for parsing, `--help`, and shell completion. Value options accept both `--label text` and `--label=text`. Invalid arguments are rejected before connecting to the server.
+
 ## Launch and status

 ```bash
@@ -65,7 +67,7 @@ In an interactive terminal, `machine add` discovers running sessions and lets yo

 Changes apply automatically to open local Herdr clients, normally within a second. Added or enabled machines connect in the background; renaming does not reconnect. Removing or disabling disconnects only that machine and leaves its remote sessions running. Removing the machine you are viewing returns to Local, or shows Local as unavailable until it reconnects. Each profile stores an opaque ID, label, SSH target, explicit remote session, and enabled state in client state. Herdr does not store passwords, private keys, or other SSH credentials.

-Use `herdr machine status [<label-or-id>] [--json]` for fresh, noninteractive SSH and remote Herdr checks. `reachable` describes this check, not a TUI's current connection. Use `herdr machine reconnect <label-or-id>` in a terminal for SSH authentication and verification; it does not install or update Herdr. Open clients retry failed connections within 30 seconds. Clicking `! auth` or `! error` shows the latest error and CLI guidance; collapsed sidebars show `!`. See [Recovering SSH authentication](/docs/connecting-machines/#recovering-ssh-authentication) for platform limits. For remote setup, use `herdr --remote workbox`, adding `--session <name>` only for a named session.
+Use `herdr machine status [<label-or-id>] [--json]` for fresh, noninteractive SSH and remote Herdr checks. `reachable` describes this check, not a TUI's current connection. Use `herdr machine reconnect <label-or-id>` in a terminal for SSH authentication and verification; it does not install or update Herdr. Open clients retry failed connections within 30 seconds. Clicking `! auth` or `! error` retries the connection; a failed attempt shows the latest error and CLI guidance; collapsed sidebars show `!`. See [Recovering SSH authentication](/docs/connecting-machines/#recovering-ssh-authentication) for platform limits. For remote setup, use `herdr --remote workbox`, adding `--session <name>` only for a named session.

 Workspace, tab, pane IDs, and agent names belong to a single server. Selecting a machine in the UI does not retarget CLI commands. Use the global **prefix** `--machine <label-or-id>` to route API commands to a saved SSH machine:

@@ -11,10 +11,12 @@ Herdr requests SSH compression to reduce screen-update traffic on limited connec

 ### Recovering SSH authentication

-On Linux and macOS clients, when `remote.manage_ssh_config=true`, Herdr shares an approved OpenSSH connection across machine add, the sidebar, and saved-machine API commands. Run `herdr machine status [<label-or-id>] [--json]` for fresh, noninteractive checks. **Reachable** means the remote Herdr server is available now, not that every open TUI is connected. Run `herdr machine reconnect <label-or-id>` in a terminal to complete native SSH authentication and verify the saved machine. It does not install or update Herdr. Open clients recheck failed connections within 30 seconds; no restart is needed. Clicking **`! auth`**, **`! error`**, or a failed connection's reconnecting status shows a notice with its latest error and the relevant CLI command. It never opens a credential popup. The rest of the machine row keeps its normal expand/collapse behavior.
+On Linux and macOS clients, when `remote.manage_ssh_config=true`, Herdr shares an approved OpenSSH connection across machine add, the sidebar, and saved-machine API commands. Run `herdr machine status [<label-or-id>] [--json]` for fresh, noninteractive checks. **Reachable** means the remote Herdr server is available now, not that every open TUI is connected. Run `herdr machine reconnect <label-or-id>` in a terminal to complete native SSH authentication and verify the saved machine. It does not install or update Herdr. Open clients recheck failed connections within 30 seconds; no restart is needed. Clicking **`! auth`**, **`! error`**, or a reconnecting status retries the connection; if it fails, a notice shows the latest error and relevant CLI command. It never opens a credential popup.

 The shared connection uses `ControlPersist 600` (10 minutes of idle time); this is not MFA validity. Active connections can remain open, while corporate policy, the SSH server, or the network may end them sooner. Local Windows recovery is not supported yet. For unmanaged SSH connections, authentication remains your responsibility: running `ssh` by itself does not grant Herdr approval unless it uses the shared ControlPath. Host-key checking is unchanged; an unknown or changed host key remains **Attention**.

+Saved TUI connections check whether an existing shared SSH connection can open a new channel. CLI status and API commands check only after an initial read-only connection failure. If reuse fails while a fresh connection to the same host succeeds, Herdr retires the old connection from reuse and reconnects. Existing channels stay open. A fresh connection that needs authentication or rejects the host key does not trigger this recovery. API commands retry connection setup at most once and never repeat a request that may already have changed remote state.
+
 ## Before you connect

 You need normal SSH access to the remote machine. Verify it first:
@@ -88,7 +90,7 @@ Removing or disabling the machine you are viewing returns you to Local. If Local
 ## Connection problems

 - **Reconnecting:** Herdr retries automatically after a network interruption, sleep, or SSH failure. Repeated failures increase the delay up to two minutes; brief successful connections do not reset it. A connection must remain healthy for a minute before the next interruption gets a fast retry. SSH connections are checked for application-level activity and probed when quiet, so a broken connection does not stay Online indefinitely. Local detects native connection closure or failure instead of using remote health probes.
- **Attention:** The target needs an action such as authentication, host-key approval, or a compatible server. Other machines remain usable. **`! auth`** means authentication failed; **`! error`** indicates another issue. Click the badge for the error and a CLI command. In a collapsed sidebar, either appears as `!`.
+- **Attention:** The target needs an action such as authentication, host-key approval, or a compatible server. Other machines remain usable. **`! auth`** means authentication failed; **`! error`** indicates another issue. Click the badge to retry; if it fails, a notice shows the fresh error and a CLI command. In a collapsed sidebar, either appears as `!`.
 - **Saved-machine file error:** An unreadable or invalid catalog leaves current connections unchanged. Herdr shows a notice and automatically retries reading it.

 When both installations support bridge idle cleanup, saved-machine connections to Linux and macOS also close their remote bridge after a minute without traffic in either direction. Sleep counts toward that deadline, which is checked when the host wakes. Quiet healthy connections exchange health checks; watching continuous output does not require typing. Cleanup leaves the remote Herdr server, sessions, and pane processes running. Older installations remain compatible without this optional cleanup.
@@ -75,7 +75,11 @@ Linux と macOS では、ホストから見えるラッパーが実際のエー

 スクリーンマニフェスト方式のエージェントでは、blocked の検出は意図的に厳格です。Herdr が `blocked` と判定するのは、ライブの下部バッファスナップショットが既知の承認・質問・許可 UI にマッチしたときだけです。既知のエージェントでどのマニフェストルールにもマッチしない場合、Herdr は `idle` にフォールバックし、explain の出力ではそのフォールバックに `default_known_agent_idle_fallback` というラベルを付けます。

-つまり、見慣れない新しいエージェントプロンプトは、Herdr がその画面の形を学習するまで、最初は `blocked` ではなく `idle` と表示されることがあります。こうしたやり取りによって Herdr が入力を送ったり破壊的な操作をしたりすることはありません。影響するのは表示上の状態と wait だけです。
+見慣れない新しいエージェントプロンプトは、Herdr がその画面の形を学習するまで、`blocked` ではなく `idle` と表示されることがあります。検出自体は入力を送りませんが、誤った idle 状態を信頼する自動処理は承認ダイアログへ入力してしまう可能性があります。予期しないプロンプトでは次の入力を送る前に画面を確認してください。idle は操作を承認する許可ではありません。
+
+Antigravity と Grok は、バックグラウンドのタスク、モニター、サブエージェントが動いていても、プロンプトに戻ると idle と判定されます。`agent wait` と `agent prompt --wait` はエージェントの状態を監視し、それらのジョブの完了は待ちません。
+
+Ctrl+Z でエージェントを中断しても、同じプロセスがシェルやエージェント以外のコマンドの背後で生きている間は、名前、セッション参照、フックの権限を保持します。`fg` で戻ると同じ識別情報を使えます。別の認識済みエージェントがフォアグラウンドを引き継ぐ場合は対象外です。識別情報が残っていても、中断中のエージェントが入力を受け取れるとは限りません。送信前にペインを確認してください。

 ## 検出マニフェスト

@@ -7,6 +7,8 @@ Herdr の CLI は、インテグレーションやエージェントが使うの

 ほとんどのコマンドは JSON レスポンスを出力します。決定的な自動化が欲しいときはスクリプトから使ってください。

+API を呼び出すコマンドでは、引数の解析、`--help`、シェル補完が同じ引数定義を使います。値を取るオプションは `--label text` と `--label=text` の両方を受け付けます。不正な引数はサーバーに接続する前に拒否されます。
+
 ## 起動とステータス

 ```bash
@@ -63,7 +65,7 @@ herdr machine remove <profile-id>

 変更は、開いているローカルの Herdr クライアントに通常 1 秒以内に自動反映されます。追加または有効化したマシンにはバックグラウンドで接続し、名前の変更では再接続しません。削除または無効化すると、そのマシンだけが切断され、リモートセッションは動き続けます。表示中のマシンを削除すると Local に戻ります。Local に接続できない場合は、再接続するまで利用不可と表示します。各プロファイルは、不透明な ID、ラベル、SSH 接続先、明示的なリモートセッション名、有効状態をクライアントの状態ファイルに保存します。パスワード、秘密鍵、その他の SSH 認証情報は保存しません。

-`herdr machine status [<label-or-id>] [--json]` は SSH とリモート Herdr を非対話式で確認します。`reachable` は今回の確認結果で、TUI の接続状態ではありません。ターミナルで `herdr machine reconnect <label-or-id>` を実行すると認証と検証を行いますが、インストールや更新は行いません。開いているクライアントは 30 秒以内に再試行します。`! auth` または `! error` をクリックすると最新のエラーと CLI コマンドを表示します。折りたたみ時は `!` です。対応環境は [SSH 認証の復旧](/ja/docs/connecting-machines/#ssh-認証の復旧)を参照してください。セットアップには `herdr --remote workbox` を使い、名前付きセッションの場合だけ `--session <name>` を追加します。
+`herdr machine status [<label-or-id>] [--json]` は SSH とリモート Herdr を非対話式で確認します。`reachable` は今回の確認結果で、TUI の接続状態ではありません。ターミナルで `herdr machine reconnect <label-or-id>` を実行すると認証と検証を行いますが、インストールや更新は行いません。開いているクライアントは 30 秒以内に再試行します。`! auth` または `! error` をクリックすると再試行し、失敗した場合は最新のエラーと CLI コマンドを表示します。折りたたみ時は `!` です。対応環境は [SSH 認証の復旧](/ja/docs/connecting-machines/#ssh-認証の復旧)を参照してください。セットアップには `herdr --remote workbox` を使い、名前付きセッションの場合だけ `--session <name>` を追加します。

 ワークスペース、タブ、ペインの ID とエージェント名はサーバーごとに独立しています。UI での選択は CLI の接続先を変えません。保存済み SSH マシンへ API コマンドを送るには、グローバルな**プレフィックス** `--machine <label-or-id>` を指定します。

@@ -424,13 +426,14 @@ herdr integration status [--outdated-only]

 ```bash
 herdr plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]
+herdr plugin update [<plugin_id|owner/repo[/subdir...]>...] [--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` を渡してください。
+`plugin install` は `ogulcancelik/herdr-plugin-examples/worktree-bootstrap` のような GitHub 省略記法のみを受け付けます。`git` を使い、対話的なターミナルでは信頼プレビューを表示し、サポートされるマニフェストのビルドコマンドを実行し、GitHub インストールを Herdr 管理のディレクトリに保存します。非対話的なインストールには `--yes` を使ってください。`plugin update` は対象を省略すると GitHub 管理の全プラグインを、指定すると該当する id または GitHub ソースだけを更新します。記録された ref を使い、変更のないコミットと一括更新時のローカルリンクをスキップします。再インストールは新しいディレクトリを作成します。実行中のプラグインは元のファイルを、新しい呼び出しは新しい版を使います。ローカルにリンクされたプラグインへの上書きインストールは拒否されます。プラグインのマニフェストは `min_herdr_version` を宣言しなければならず、プラグインがより新しい Herdr バイナリを要求する場合、install と link は失敗します。`plugin list` はデフォルトで人間可読です。生の API レスポンスが欲しいときは `--json` を渡してください。

 ローカル開発:

@@ -439,7 +442,7 @@ 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 の範囲外です。
+`plugin link` は `herdr-plugin.toml` を含むプラグインディレクトリ、またはマニフェストへの直接パスを受け付けます。ローカルチェックアウトからプラグインを作成・テストしている間はこれが正しいコマンドです。`plugin unlink` と `plugin uninstall` は登録を解除し、実行中のプラグインが完了できるようファイルを残します。更新や再インストールも古い版を保持し、新しい呼び出しは設定の再読み込みなしで新しい版を使います。使用中のサーバーが終了した後、次に成功したインストール／更新、またはサーバー起動時に不要な管理インストールを削除します。設定の再読み込みでは解放されません。プラグインは親コマンドやペインの終了前に、切り離したバックグラウンドプロセスを停止する必要があります。サーバー終了後も残るプロセスは削除から保護されません。削除追跡のない旧インストールとローカルリンクのファイルは保持します。GitHub インストールの場合、uninstall はプラグイン id と、install で使うのと同じ `owner/repo[/subdir...]` 省略記法の両方を受け付けます。アクション、イベントフック、ペイン、リンクハンドラーはマニフェストで宣言します。ランタイムでのアクション登録は v1 の範囲外です。

 設定ディレクトリ:

@@ -474,7 +477,7 @@ herdr plugin pane close <pane_id>

 `plugin pane open` は、プラグインがリンクされ、有効で、現在のプラットフォームと互換であることを要求します。マニフェストで宣言された `[[panes]]` コマンドを Herdr 管理のターミナルペインとして起動します。マニフェストのデフォルトは `overlay` で、アクティブなペインの上に一時的なズームオーバーレイを開きます。分割、新しいタブ、ズームされたペイン、またはタブレイアウトを変更しないセッションモーダルな `popup` として開くこともできます。`--width` と `--height` は、外側のポップアップ寸法をターミナルセル数または `80%` のような割合で指定します。省略した寸法はデフォルトでターミナルの半分になり、小さすぎる値はポップアップの最小サイズに制限されます。ポップアップは Herdr ペインではなく、`HERDR_PANE_ID` を受け取らず、pane API やエージェント API に参加しません。ターミナル以外のネイティブなプラグインペインは今後の対応面です。

-新しいペインでは `TERM_PROGRAM=herdr` として識別され、`TERM_PROGRAM_VERSION` には Herdr のバージョンが設定されます。`TERM=xterm-256color` と `COLORTERM=truecolor` は維持されます。Herdr は、明示的な起動環境の値を適用する前に、継承した外側のターミナルのセッションマーカー（iTerm2、WezTerm、Kitty、Windows Terminal、tmux、screen、Zellij）、iTerm2 の `LC_TERMINAL` 識別子、既知の Claude Code、Codex、OMP セッションマーカーを削除します。これにより、新しいペインがサーバーを最初に起動したターミナルやエージェントのセッションを名乗ることを防ぎます。API キーやディスプレイ設定を含む通常の環境変数は、アタッチ中クライアントの環境に置き換えられず、引き続き継承されます。SSH エージェント転送には独自の再接続処理があります。このクリーンアップによって既存ペインのプロセスは変更されません。
+新しいペインでは `TERM_PROGRAM=herdr` として識別され、`TERM_PROGRAM_VERSION` には Herdr のバージョンが設定されます。`TERM=xterm-256color` と `COLORTERM=truecolor` は維持されます。リサイズ時に Herdr がテキストを折り返し直すため、`fish_handle_reflow=0` も設定します。継承した値や明示的な `fish_handle_reflow` の指定は優先されます。Herdr は、明示的な起動環境の値を適用する前に、継承した外側のターミナルのセッションマーカー（iTerm2、WezTerm、Kitty、Windows Terminal、tmux、screen、Zellij）、iTerm2 の `LC_TERMINAL` 識別子、既知の Claude Code、Codex、OMP セッションマーカーを削除します。これにより、新しいペインがサーバーを最初に起動したターミナルやエージェントのセッションを名乗ることを防ぎます。API キーやディスプレイ設定を含む通常の環境変数は、アタッチ中クライアントの環境に置き換えられず、引き続き継承されます。SSH エージェント転送には独自の再接続処理があります。このクリーンアップによって既存ペインのプロセスは変更されません。

 `--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 管理の変数は、呼び出し側が与えた環境変数と衝突した場合も権威を保ちます。

@@ -492,6 +492,8 @@ position = "bottom-right"

 macOS では、`system` は最初に `terminal-notifier` を試し、利用できない場合や失敗した場合は `/usr/bin/osascript` にフォールバックします。このフォールバックは通知センターで Script Editor として表示され、ホストターミナルをアクティブにできません。`brew install terminal-notifier` で `terminal-notifier` をインストールできます。対応するターミナルを Herdr が検出できた場合、通知のクリック時にそのターミナルアプリをアクティブにできます。または、`terminal` を選んで対応する外側のターミナルに通知を送信させてください。

+Windows の `system` 通知は通知センターに残ります。クリックすると、実行中の Herdr クライアントで元のペインを選択し、Windows が対象ウィンドウを取得できればターミナルを前面に出します。閉じたクライアントを開き直したり、再起動したサーバーのペインを選択したりはできません。Windows Terminal ではウィンドウを前面に出せますが、外側の別タブを確実に選択することはできません。
+
 ## サウンド

 サウンド通知はローカルの Herdr クライアントで再生されます。カスタムサウンドは mp3 ファイルでなければなりません。相対パスは設定ファイルのディレクトリから解決されます。
@@ -11,7 +11,7 @@ Herdr は、帯域が限られた接続で画面更新の通信量を減らす

 ### SSH 認証の復旧

-Linux と macOS で `remote.manage_ssh_config=true` の場合、マシン追加、サイドバー、API 操作は承認済み OpenSSH 接続を共有します。`herdr machine status [<label-or-id>] [--json]` は認証を求めず、現在の接続状態を確認します。**reachable** はリモート Herdr が利用可能という意味で、各 TUI の接続状態ではありません。ターミナルで `herdr machine reconnect <label-or-id>` を実行すると、SSH 認証後に保存済みマシンを検証します。インストールや更新は行いません。開いているクライアントは 30 秒以内に再試行し、再起動は不要です。**`! auth`**、**`! error`**、失敗後の再接続ステータスをクリックすると、最新のエラーと CLI コマンドが通知に表示されます。認証ポップアップは開きません。マシン行の展開・折りたたみは変更されません。
+Linux と macOS で `remote.manage_ssh_config=true` の場合、マシン追加、サイドバー、API 操作は承認済み OpenSSH 接続を共有します。`herdr machine status [<label-or-id>] [--json]` は認証を求めず、現在の接続状態を確認します。**reachable** はリモート Herdr が利用可能という意味で、各 TUI の接続状態ではありません。ターミナルで `herdr machine reconnect <label-or-id>` を実行すると、SSH 認証後に保存済みマシンを検証します。インストールや更新は行いません。開いているクライアントは 30 秒以内に再試行し、再起動は不要です。**`! auth`**、**`! error`**、再接続ステータスをクリックすると再試行し、失敗した場合は最新のエラーと CLI コマンドを通知に表示します。認証ポップアップは開きません。

 共有接続の `ControlPersist 600` はアイドル状態の 10 分を表すもので、MFA の有効期間ではありません。通信中の接続は維持されますが、企業ポリシー、SSH サーバー、ネットワークによってはそれより早く終了します。ローカル Windows の復旧はまだ対応していません。管理対象外の SSH 接続の認証は利用者の責任です。共有 ControlPath を使わずに `ssh` を実行するだけでは、Herdr の承認にはなりません。ホスト鍵の検証は緩和されず、未知または変更されたホスト鍵は引き続き **Attention** です。

@@ -88,7 +88,7 @@ herdr machine remove <profile-id>
 ## 接続の問題

 - **Reconnecting:** ネットワーク中断、スリープ、SSH 障害の後は自動で再試行します。失敗が続くと待機間隔は最大 2 分まで延び、短時間だけ接続に成功してもリセットされません。1 分間安定して接続できると、次の中断では再び短い間隔で再試行します。SSH 接続はアプリケーションの通信を監視し、通信がない間はヘルスチェックを行うため、切れた接続が Online のままになりません。Local はリモート用のプローブではなく、ネイティブ接続の終了や失敗を検知します。
- **Attention:** 認証、ホスト鍵の承認、互換サーバーの準備などが必要です。ほかのマシンは利用できます。**`! auth`** は認証失敗、**`! error`** は別の問題を示します。バッジをクリックするとエラーと CLI コマンドを表示します。折りたたみ時はどちらも `!` です。
+- **Attention:** 認証、ホスト鍵の承認、互換サーバーの準備などが必要です。ほかのマシンは利用できます。**`! auth`** は認証失敗、**`! error`** は別の問題を示します。バッジをクリックすると再試行し、失敗した場合は新しいエラーと CLI コマンドを通知に表示します。折りたたみ時はどちらも `!` です。
 - **保存済みマシンのファイルエラー:** カタログを読み取れない、または内容が不正な場合、現在の接続は変更しません。通知を表示して自動で読み取りを再試行します。

 両端のインストールがブリッジのアイドル終了に対応している場合、Linux と macOS への保存済みマシン接続は、どちらの方向にも通信がない状態が 1 分続くとリモートブリッジを終了します。スリープ時間も含み、復帰時に期限を確認します。正常なアイドル接続ではヘルスチェックを交換するため、継続的な出力を見るためにキーを入力する必要はありません。ブリッジ終了後もリモートサーバー、セッション、ペインのプロセスは動き続けます。古いインストールとは、この追加機能なしで接続できます。
@@ -61,7 +61,7 @@ Herdr は Linux/macOS の統合設定と全プラットフォームの新規フ

 どのインテグレーションも、エージェントが今どのセッションにいるかを Herdr に伝えるので、サーバーの再起動後に Herdr がそのセッションを resume できます。`[session] resume_agents_on_restore = false` で無効にできます。

-Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、MastraCode のインテグレーションは、エージェントの状態も報告します。報告している間、Herdr は画面を読む代わりにその報告を使います。その他のインテグレーションでは、状態は画面検出に任せます。
+Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、MastraCode のインテグレーションは、エージェントの状態も報告します。報告している間、Herdr は画面を読む代わりにその報告を使います。Codex は `--no-daemon` で起動した場合にターン状態を報告し、表示中のブロッカーは引き続き画面検出で扱います。その他のインテグレーションでは、状態は画面検出に任せます。

 エージェントネイティブのセッション復元には最新の 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`、Qwen Code は `1`、Letta Code は `1`、Cursor Agent CLI は `1`、Grok CLI は `2`、OpenCode は `5`、Kilo Code CLI は `1`、Hermes Agent は `5`、MastraCode は `1`、Antigravity CLI は `1` です。インストール済みバージョンは `herdr integration status` で確認してください。

@@ -125,7 +125,7 @@ Codex フックをインストールします:
 herdr integration install codex
 ```

-Codex フックは、他のインテグレーションと同じローカルソケット API を通じてセッション識別を報告します。Codex の状態は Herdr のスクリーンマニフェスト検出から得られます。
+Codex を `--no-daemon` で起動すると、フックがローカルソケット API を通じてセッション識別とターンの開始・終了を報告します。表示中のブロッカーやフックが使えない場合は、引き続き画面検出が補います。共有 Codex デーモンは別のペインへフックを送ることがあるため、確実な報告には `--no-daemon` を使ってください。デーモンの自動起動を無効にするだけでは、既存のデーモンは停止しません。

 Herdr はデフォルトで `~/.codex` を使い、`CODEX_HOME` が設定されていればそちらを使います。Codex の設定ディレクトリはあらかじめ存在している必要があります。インストールは `herdr-agent-state.sh` を書き込み、`hooks.json` を更新し、`config.toml` に `[features] hooks = true` があることを保証します。非推奨のトップレベル `codex_hooks` フラグが存在すれば削除もします。アンインストールは `hooks.json` から Herdr のエントリを削除してフックスクリプトを削除しますが、`config.toml` は変更しません。

@@ -64,6 +64,12 @@ Herdr はマウスネイティブです。キーバインドをひとつも覚

 Goto ピッカー (`prefix+g`) は、各エージェントとターミナルをワークスペースごとに一行ずつ表示します。分割タブのペインも隠さず表示されます。行をクリックするか Enter を押すと、そのペインへ直接移動します。`/` で名前、エージェントの種類、タブ、ワークスペース、ブランチ、パスを検索できます。検索入力中でなければ上下矢印キーまたは `j/k` で行を移動します。左右矢印キーは前後のワークスペースの最初のエージェントまたはターミナルへ移動し、端では折り返しません。検索入力中は左右矢印キーでテキストカーソルを動かします。`b/w/i/d` で blocked、working、idle、done のエージェントに絞り込み、`a` ですべてのターミナルに戻します。選択した移動先の場所とパスは一覧の下に表示されます。一覧が収まらない場合は、マウスホイール、スクロールバーのトラックのクリック、つまみのドラッグで、移動先を開かずにスクロールできます。

+Esc または Ctrl+[ でワークスペースナビゲーションを終了します。Go To では、Shift が必要な配列でも `/` で検索を開けます。
+
+ペインへの入力はアプリが要求するキーボードモードに従います。通常のシェルには Ctrl+Shift+letter を制御バイトとして送り、表現できない Super、Hyper、Meta の組み合わせは送りません。Kitty キーボード入力を使うアプリには、要求した修飾キーとキーイベントを送ります。report-all モード以外では、修飾付き Enter、Tab、Backspace の解放レポートは送りません。テンキーと修飾キー単独の押下も転送しません。
+
+非ラテン文字の配列では、Ctrl+W など Ctrl 単独の組み合わせに、Kitty 対応ホストが報告する物理的なベースキーを使えます。ラテン文字の配列、Ctrl+Shift、AltGr は配列上の意味を保持します。物理キーを報告しないターミナルでは、同じ配列非依存のショートカットは使えません。
+
 ## テキスト欄の編集

 Herdr の名前入力、worktree のブランチ名、フィルター、コピーモードの検索欄では、カーソル位置で編集できます。以下は Herdr 自身の入力欄の操作であり、ペイン内のシェルやエージェントの操作は変わりません。
@@ -13,6 +13,8 @@ Herdr はペインをバックグラウンドサーバーで動かし続けま

 サーバーの完全停止後に Herdr が再起動すると、保存されたセッションの形を復元します。デタッチ、サーバー再起動、画面履歴リプレイ、エージェントネイティブのセッション復元、ライブハンドオフでそれぞれ何が生き残るかは[セッション状態と復元](/ja/docs/session-state/)を参照してください。

+Linux と macOS のサーバーは `SIGHUP` を無視するため、起動元シェルの切断ではペインは停止しません。意図的に停止するには `herdr server stop` または `SIGTERM` を使ってください。以前 `SIGHUP` を使っていたスクリプトは変更が必要です。終了ログには停止理由が記録されます。
+
 ## 名前付きセッション

 独立した Herdr サーバーが欲しいときは名前付きセッションを使います。
@@ -174,6 +174,7 @@ process.exit(result.status ?? 1);

 ```bash
 herdr plugin install ogulcancelik/herdr-plugin-examples/agent-telegram-notify
+herdr plugin update
 herdr plugin config-dir examples.agent-telegram-notify
 herdr plugin list
 herdr plugin action list --plugin examples.agent-telegram-notify
@@ -191,10 +192,15 @@ herdr plugin log list --plugin example.layout
 ```

 `plugin install` は `owner/repo/subdir` のような GitHub 省略記法のみを受け付けます。
-`git` でクローンし、対話的なターミナルではプレビューを表示し、サポートされる
-ビルドコマンドを実行し、チェックアウトを Herdr 管理のプラグインデータの下に保存して
-登録します。非対話的なインストールには `--yes` を使ってください。GitHub 管理の
-プラグインを再インストールすると、その管理チェックアウトが置き換えられます。
+`git` でクローンし、対話的なターミナルではプレビューを表示し、新しい Herdr 管理の
+インストールディレクトリでビルドして登録します。非対話的なインストールには
+`--yes` を使ってください。更新や再インストール後も、実行中のコマンドとペインは
+元のファイルを使い続け、新しい呼び出しは設定の再読み込みなしで新しい版を使います。
+既存のプロセスは再起動されず、起動フックは通常どおり次のサーバー起動時に実行されます。
+`plugin update` は対象を省略すると GitHub 管理の全プラグインを更新します。
+プラグイン id または GitHub ソースを指定すれば、その対象だけを更新します。
+インストール時の ref を再取得し、コミットが変わっていなければスキップします。
+一括更新ではローカルにリンクされたプラグインを無視します。非対話的な更新には `--yes` を使います。
 インストール済みおよびリンク済みのプラグインと、その有効・無効の状態は現在の
 ユーザー全体で共有され、すべての Herdr セッションから利用できます。Herdr サーバーが
 動作していないときでも `plugin install` と `plugin link` で登録できます。
@@ -206,12 +212,15 @@ Herdr 0.7.3 の名前付きセッションだけにインストールしたプ
 `plugin config-dir <id>` はセットアップドキュメントやシェルスクリプト向けに
 設定ディレクトリを表示します。

-`plugin uninstall <id-or-source>` はプラグインの登録を解除します。GitHub 管理の
-インストールでは管理チェックアウトも削除し、プラグイン id と、install で使うのと
-同じ `owner/repo[/subdir...]` 省略記法の両方を受け付けます。`plugin unlink <id>` は
-登録解除のみを行いファイルには触れないため、ローカル開発に便利です。v1 に独立した
-`plugin update` はありません。管理プラグインを更新するには GitHub から
-再インストールしてください。
+`plugin uninstall <id-or-source>` は登録を解除し、プラグイン id または install と同じ
+`owner/repo[/subdir...]` 省略記法を受け付けます。更新、再インストール、アンインストール後も
+実行中のプラグインが完了できるようファイルを保持します。使用中のサーバーが終了した後、
+次に成功したインストール／更新、またはサーバー起動時に、不要な管理インストールを削除します。
+設定の再読み込みでは古いインストールを解放しません。サーバー停止前にプラグインの作業を
+止めてください。サーバー終了後も残るプロセスは削除から保護されません。プラグインは
+親コマンドやペインが終了する前に、切り離したバックグラウンドプロセスを停止する必要があります。
+削除追跡のない旧インストール、設定、状態は保持されます。
+`plugin unlink <id>` は登録解除のみを行いファイルには触れないため、ローカル開発に便利です。

 サンプル集のリポジトリは `ogulcancelik/herdr-plugin-examples` です。
 `agent-telegram-notify`、`github-link-preview`、`dev-layout-bootstrap` を含む
@@ -49,6 +49,19 @@ Windows ビルドは安定版とプレビューの両方のアップデートチ

 ローカル永続セッションは、クライアントをデタッチした後やターミナルウィンドウを閉じた後も動作し続けます。Windows OpenSSH から起動したサーバーとペインプロセスもログアウト後に存続します。再接続するには `herdr` をもう一度実行してください。

+管理者権限の Windows サーバーは、既定では管理者クライアントを必要とします。管理者権限の SSH ログインから起動した場合も同じです。通常権限のサーバーには、同じアカウントの通常・管理者クライアントの両方が接続できます。接続してもサーバーの権限は変わりません。
+
+管理者セッションを通常クライアントと意図的に共有する場合は、次を設定します:
+
+```toml
+[server]
+allow_unelevated_clients = true
+```
+
+この Windows 専用設定は既定では無効で、自動起動を含む新しいサーバーの起動時に適用されます。設定の再読み込みでは実行中サーバーの接続権限は変わりません。代わりに管理者ターミナルで `herdr server --allow-unelevated-clients`（名前付きセッションでは `herdr --session <name> server --allow-unelevated-clients`）を使うと、そのサーバープロセスだけで共有できます。このフラグは設定が false でも共有を有効にします。
+
+どちらも同じアカウントの通常権限プロセスによる管理者ペインの操作を許可します。他のアカウントは引き続き接続できません。設定で有効にしない限り、再起動後もフラグを指定する必要があります。既存サーバーは更新版で停止・再起動するまで以前の接続ポリシーを維持します。停止するとペインも閉じます。設定と復旧ファイルのアカウント単位の権限は変わりません。
+
 Windows のエージェントプロセス検出は、ペインのシェルの子孫プロセスをスキャンし、npm/Node や Git Bash のプロセスチェーンを含む直接のエージェントと一般的なコマンドラッパーを認識します。Git Bash から起動したエージェントはエミュレートされた `exec` 境界を越えて追跡されますが、Unix のフォアグラウンドプロセスグループ検出と同じものではありません。

 Windows でインテグレーションをインストールできるのは、現在 Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、OpenCode、Kilo Code CLI、Droid、Kimi Code CLI、Qoder CLI、Antigravity CLI です。利用可能な対象は Unix より少なく、インストール形式が Windows で未対応のインテグレーションは表示されないか拒否されます。
@@ -113,6 +126,8 @@ Herdr のペインテキストコピーは Windows で動作します。ペイ

 テキストの貼り付けには Windows Terminal で `ctrl+shift+v` を使ってください。複数行テキストの貼り付けはブラケット付きなので、シェルやエージェントのプロンプトは各行を個別に送信せず、ひとつの貼り付けとして受け取ります。`shift` を押しながら右クリックすると、クリックを Herdr に送らずに外側ターミナルの貼り付けアクションを使えます。

+Windows クライアントは、WezTerm が完全な Win32 文字の押下・解放ペアを生のペーストマーカーで囲んだ場合にもテキストを復元します。通常のテキストが混在する場合や不完全なレポートは、この互換処理ではデコードしません。同じ形式の完全な Win32 レポートだけを含むクリップボードテキストは区別できず、同様にデコードされます。
+
 ## Windows で未サポート

 | 機能 | 状況 |
@@ -64,6 +64,12 @@ The full keymap and the binding syntax live in the [keybinding reference](/docs/

 The Goto picker (`prefix+g`) lists each agent or terminal on its own row, grouped by workspace. Split tabs never hide their panes behind another row. Click a row or press Enter to jump directly to it. Press `/` to search names, agent kinds, tabs, workspaces, branches, or paths; use Up/Down or `j/k` to move between rows when not typing a search. Left/Right jumps to the first agent or terminal in the previous/next workspace section, without wrapping. While editing a search, Left/Right moves the text cursor instead. Outside search, `b/w/i/d` filter blocked, working, idle, or done agents, and `a` shows all terminals again. The selected destination's location and path appear below the list. When the list overflows, use the mouse wheel, click the scrollbar track, or drag its thumb to scroll without opening a destination.

+Press Esc or Ctrl+[ to leave workspace navigation. In the Go To picker, `/` also opens search on layouts that require Shift to type it.
+
+Pane input follows the keyboard modes requested by the app. Plain shells receive Ctrl+Shift+letter as its control byte; Super, Hyper, and Meta chords are dropped when the pane cannot represent them. Apps using Kitty keyboard input receive the modifiers and key events they request. Without report-all mode, modified Enter, Tab, and Backspace do not receive release reports. Keypad keys and modifier-only presses are not forwarded.
+
+On non-Latin layouts, Ctrl-only shortcuts such as Ctrl+W can use the physical base key reported by a Kitty-capable host. Latin layout characters, Ctrl+Shift chords, and AltGr keep their layout meaning. Terminals that do not report physical keys cannot provide the same layout-independent shortcuts.
+
 ## Editing text fields

 Herdr's naming dialogs, worktree branch fields, filters, and copy-mode search support editing at the cursor. These shortcuts apply to Herdr-owned fields, not to the shell or agent inside a pane.
@@ -13,6 +13,8 @@ Detach the client with `ctrl+b q`; panes and agents keep running. Reattach by ru

 When Herdr starts again after a full server stop, it restores the saved session shape. For what survives detach, server restart, screen history replay, native agent session restore, and live handoff, see [Session state and restore](/docs/session-state/).

+On Linux and macOS, the server ignores `SIGHUP`, so a hangup from its launching shell does not stop the panes. To stop it deliberately, use `herdr server stop` or `SIGTERM`; scripts that previously used `SIGHUP` must change. Shutdown logs record the reason.
+
 ## Named sessions

 Use named sessions when you want independent Herdr servers.
@@ -75,7 +75,11 @@ Herdr 能识别这些智能体,并从它们在屏幕上绘制的内容读取状

 对屏幕清单类智能体,blocked 检测刻意从严。只有当实时底部缓冲区快照匹配已知可见的审批、提问或权限 UI 时,Herdr 才标记 `blocked`。对已知智能体,如果没有任何清单规则匹配,Herdr 会回退到 `idle`,并在 explain 输出中把该回退标记为 `default_known_agent_idle_fallback`。

-这意味着不常见的新智能体提示可能一开始显示为 `idle` 而不是 `blocked`,直到 Herdr 学会那种屏幕形态。这些交互不会让 Herdr 发送输入或执行破坏性操作;它们只影响可见状态和等待。
+不常见的新智能体提示可能显示为 `idle` 而不是 `blocked`,直到 Herdr 学会那种屏幕形态。检测本身不会发送输入,但信任错误 idle 状态的自动化可能向审批对话框输入内容。遇到意外提示时,请先检查再继续发送输入;idle 状态不代表获准批准操作。
+
+Antigravity 和 Grok 回到提示符时即被视为 idle,即使后台任务、监视器或子智能体仍在运行。`agent wait` 和 `agent prompt --wait` 观察的是智能体状态,不是这些任务是否完成。
+
+用 Ctrl+Z 挂起智能体后,只要同一个进程仍在 shell 或其他非智能体命令后面存活,其名称、会话引用和钩子权限就会保留。用 `fg` 返回后继续使用该身份。另一个被识别的智能体接管前台的情况不在此范围内。保留身份不代表挂起的智能体能接收输入;发送提示前请检查窗格。

 ## 检测清单

@@ -7,6 +7,8 @@ Herdr 的 CLI 通过与集成和智能体相同的本地 socket API 与运行中

 大多数命令输出 JSON 响应。需要确定性自动化时,从脚本中使用它们。

+调用 API 的命令使用同一组参数定义进行解析、显示 `--help` 和生成 shell 补全。带值的选项同时接受 `--label text` 和 `--label=text`。无效参数会在连接服务器之前被拒绝。
+
 ## 启动与状态

 ```bash
@@ -63,7 +65,7 @@ herdr machine remove <profile-id>

 更改会自动应用到已打开的本地 Herdr 客户端，通常在一秒内生效。新增或启用的机器在后台连接；重命名不会重新连接。移除或禁用只会断开该机器，远程会话仍会继续运行。移除正在查看的机器会返回 Local；如果 Local 不可用，则显示不可用状态，直到重新连接。每份配置在客户端状态文件中保存一个不透明 ID、标签、SSH 目标、明确的远程会话名和启用状态。Herdr 不保存密码、私钥或其他 SSH 凭据。

-`herdr machine status [<label-or-id>] [--json]` 可非交互式检查 SSH 和远程 Herdr。`reachable` 表示本次检查成功，不代表 TUI 当前已连接。在终端运行 `herdr machine reconnect <label-or-id>` 可认证并验证连接，不会安装或更新 Herdr。已打开的客户端会在 30 秒内重试。点击 `! auth` 或 `! error` 可查看最新错误和 CLI 命令；侧边栏折叠时显示 `!`。平台限制请参阅[恢复 SSH 认证](/zh-cn/docs/connecting-machines/#恢复-ssh-认证)。需要远程设置时使用 `herdr --remote workbox`，仅在命名会话时添加 `--session <name>`。
+`herdr machine status [<label-or-id>] [--json]` 可非交互式检查 SSH 和远程 Herdr。`reachable` 表示本次检查成功，不代表 TUI 当前已连接。在终端运行 `herdr machine reconnect <label-or-id>` 可认证并验证连接，不会安装或更新 Herdr。已打开的客户端会在 30 秒内重试。点击 `! auth` 或 `! error` 会重试；失败后会显示最新错误和 CLI 命令；侧边栏折叠时显示 `!`。平台限制请参阅[恢复 SSH 认证](/zh-cn/docs/connecting-machines/#恢复-ssh-认证)。需要远程设置时使用 `herdr --remote workbox`，仅在命名会话时添加 `--session <name>`。

 工作区、标签页、窗格 ID 和智能体名称仅在所属服务器内有效。UI 中的选择不会改变 CLI 的目标。使用全局**前缀** `--machine <label-or-id>` 将 API 命令发送到已保存的 SSH 机器：

@@ -424,13 +426,14 @@ herdr integration status [--outdated-only]

 ```bash
 herdr plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]
+herdr plugin update [<plugin_id|owner/repo[/subdir...]>...] [--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`。
+`plugin install` 只接受 GitHub 简写,比如 `ogulcancelik/herdr-plugin-examples/worktree-bootstrap`。它使用 `git`,在交互式终端显示信任预览,运行受支持的清单构建命令,并把 GitHub 安装保存在 Herdr 管理的目录中。非交互式安装用 `--yes`。`plugin update` 不指定目标时更新全部 GitHub 托管插件,指定目标时只更新对应的插件 id 或 GitHub 来源。它保留安装时记录的 ref,跳过未变化的提交,批量更新时忽略本地链接的插件。重新安装会创建新目录;运行中的插件保留原文件,新调用使用新安装。不允许覆盖安装到本地链接的插件之上。插件清单必须声明 `min_herdr_version`;当插件要求更新的 Herdr 二进制时,install 和 link 会失败。`plugin list` 默认是人类可读的;要原始 API 响应就传 `--json`。

 本地开发:

@@ -439,7 +442,7 @@ 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 范围内。
+`plugin link` 接受包含 `herdr-plugin.toml` 的插件目录,或直接指向清单的路径。从本地检出编写或测试插件时,它仍然是正确的命令。`plugin unlink` 和 `plugin uninstall` 注销插件并保留文件,让运行中的插件完成工作。更新和重新安装也会保留旧版本;新调用无需重新加载配置便会使用新安装。使用旧安装的服务器退出后,下一次成功安装、更新或服务器启动会清理过时的托管安装。重新加载配置不会释放旧安装。插件必须在父命令或窗格退出前停止分离的后台进程;服务器退出后仍存活的进程不受清理保护。没有清理跟踪的旧安装和本地链接文件会保留。对 GitHub 安装,uninstall 既接受插件 id,也接受与 install 相同的 `owner/repo[/subdir...]` 简写。动作、事件钩子、窗格和链接处理器在清单中声明;运行时动作注册不在 v1 范围内。

 配置目录:

@@ -474,7 +477,7 @@ herdr plugin pane close <pane_id>

 `plugin pane open` 要求插件已链接、已启用并与当前平台兼容。它把清单声明的 `[[panes]]` 命令作为 Herdr 管理的终端窗格启动。清单的默认值是 `overlay`,在活动窗格上方打开一个临时的缩放覆盖层。它也可以作为分割、新标签页、缩放窗格,或不改变标签页布局的会话级模态 `popup` 打开。`--width` 和 `--height` 以终端单元格数或 `80%` 这样的百分比设置弹窗外层尺寸;省略时默认为终端大小的一半,过小的值会限制为弹窗最小尺寸。弹窗不是 Herdr 窗格,不会收到 `HERDR_PANE_ID`,也不参与 pane 或智能体 API。非终端的原生插件窗格是之后的能力面。

-新窗格使用 `TERM_PROGRAM=herdr` 标识自身，并将 `TERM_PROGRAM_VERSION` 设为 Herdr 的版本。它们保留 `TERM=xterm-256color` 和 `COLORTERM=truecolor`。应用显式的启动环境值之前，Herdr 会移除继承的外层终端会话标记（iTerm2、WezTerm、Kitty、Windows Terminal、tmux、screen 和 Zellij）、iTerm2 的 `LC_TERMINAL` 身份，以及已知的 Claude Code、Codex 和 OMP 会话标记。这可防止新窗格冒充最初启动服务器的终端或智能体会话。API 密钥和显示设置等普通环境变量仍会继承，而不会被连接客户端的环境替换。SSH 智能体转发有自己的重连处理。现有窗格进程不受此清理影响。
+新窗格使用 `TERM_PROGRAM=herdr` 标识自身，并将 `TERM_PROGRAM_VERSION` 设为 Herdr 的版本。它们保留 `TERM=xterm-256color` 和 `COLORTERM=truecolor`。由于 Herdr 会在调整大小时重排文本,新窗格还会获得 `fish_handle_reflow=0`;继承或显式指定的 `fish_handle_reflow` 值会保留。应用显式的启动环境值之前，Herdr 会移除继承的外层终端会话标记（iTerm2、WezTerm、Kitty、Windows Terminal、tmux、screen 和 Zellij）、iTerm2 的 `LC_TERMINAL` 身份，以及已知的 Claude Code、Codex 和 OMP 会话标记。这可防止新窗格冒充最初启动服务器的终端或智能体会话。API 密钥和显示设置等普通环境变量仍会继承，而不会被连接客户端的环境替换。SSH 智能体转发有自己的重连处理。现有窗格进程不受此清理影响。

 `--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 管理的变量保持权威。

@@ -492,6 +492,8 @@ position = "bottom-right"

 在 macOS 上，`system` 会先尝试 `terminal-notifier`；如果它不可用或执行失败，则回退到 `/usr/bin/osascript`。该回退方式会在通知中心显示为 Script Editor，并且无法激活承载 Herdr 的终端。可运行 `brew install terminal-notifier` 安装 `terminal-notifier`。如果 Herdr 检测到受支持的终端，点击通知时它可以激活该终端应用。也可以选择 `terminal`，让受支持的外层终端负责发送通知。

+Windows 的 `system` 通知会保留在通知中心。点击通知会在运行中的 Herdr 客户端选择来源窗格,并在 Windows 能识别对应窗口时将终端置于前台。点击不能重新打开已关闭的客户端,也不能选择已重启服务器中的窗格。Windows Terminal 可以将所属窗口置于前台,但无法可靠地切换到另一个外层终端标签页。
+
 ## 声音

 声音通知通过本地 Herdr 客户端播放。自定义声音必须是 mp3 文件；相对路径从配置文件所在目录解析。
@@ -11,7 +11,7 @@ Herdr 会请求 SSH 压缩，以减少受限连接上的屏幕更新流量。这

 ### 恢复 SSH 认证

-在 Linux 和 macOS 上，启用 `remote.manage_ssh_config=true` 后，添加机器、侧边栏和 API 操作共享已批准的 OpenSSH 连接。运行 `herdr machine status [<label-or-id>] [--json]` 可进行新的非交互式检查。**reachable** 表示远程 Herdr 当前可用，不代表每个 TUI 都已连接。在终端运行 `herdr machine reconnect <label-or-id>` 完成原生 SSH 认证并验证已保存的机器；该命令不会安装或更新 Herdr。已打开的客户端会在 30 秒内重试，无需重启。点击 **`! auth`**、**`! error`** 或失败后的重连状态，会显示包含最新错误及 CLI 命令的通知，不会打开认证弹窗。机器行其余部分仍用于展开或折叠。
+在 Linux 和 macOS 上，启用 `remote.manage_ssh_config=true` 后，添加机器、侧边栏和 API 操作共享已批准的 OpenSSH 连接。运行 `herdr machine status [<label-or-id>] [--json]` 可进行新的非交互式检查。**reachable** 表示远程 Herdr 当前可用，不代表每个 TUI 都已连接。在终端运行 `herdr machine reconnect <label-or-id>` 完成原生 SSH 认证并验证已保存的机器；该命令不会安装或更新 Herdr。已打开的客户端会在 30 秒内重试，无需重启。点击 **`! auth`**、**`! error`** 或重连状态会重试；失败后，通知会显示最新错误和相应 CLI 命令，不会打开认证弹窗。

 共享连接使用 `ControlPersist 600`，表示空闲 10 分钟，并不表示 MFA 有效期。活动连接可以继续保持，但企业策略、SSH 服务器或网络可能更早终止连接。Windows 本地恢复尚未支持。未受管理的 SSH 连接由你负责认证；单独运行 `ssh` 不会授予 Herdr 批准，除非它使用共享 ControlPath。主机密钥检查不会放宽；未知或已更改的主机密钥仍显示为 **Attention**。

@@ -88,7 +88,7 @@ herdr machine remove <profile-id>
 ## 连接问题

 - **Reconnecting：** 网络中断、睡眠或 SSH 故障后，Herdr 会自动重试。连续失败会将间隔增加到最多两分钟，短暂连接成功不会重置间隔。连接稳定一分钟后，下一次中断才会恢复快速重试。SSH 连接会监测应用层活动并在空闲时探测，避免已断开的连接一直显示 Online。Local 使用本地连接关闭或失败来判断断线，而不是远程健康探测。
- **Attention：** 目标需要认证、批准主机密钥或准备兼容服务器等操作。其他机器仍可使用。**`! auth`** 表示认证失败，**`! error`** 表示其他问题。点击徽章可查看错误和 CLI 命令。侧边栏折叠时两者都显示为 `!`。
+- **Attention：** 目标需要认证、批准主机密钥或准备兼容服务器等操作。其他机器仍可使用。**`! auth`** 表示认证失败，**`! error`** 表示其他问题。点击徽章会重试；失败后，通知会显示本次错误和 CLI 命令。侧边栏折叠时两者都显示为 `!`。
 - **保存机器文件错误：** 目录文件无法读取或内容无效时，当前连接保持不变。Herdr 会显示通知并自动重试读取。

 当两端都支持空闲桥接清理时，连接 Linux/macOS 的保存机器会在双向均无流量一分钟后关闭远程桥接。睡眠时间也计入期限，并在唤醒时检查。正常的空闲连接会交换健康检查，持续查看输出无需键盘输入。清理不会停止远程 Herdr 服务器、会话或窗格进程。旧安装仍可兼容连接，只是不使用这项可选清理功能。
@@ -61,7 +61,7 @@ Herdr 对 Linux/macOS 上的集成配置和所有平台的新文件使用原子

 每个集成都会告诉 Herdr 智能体当前所在的会话,这样 Herdr 就能在服务器重启后恢复它。用 `[session] resume_agents_on_restore = false` 可以关闭。

-Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI 和 MastraCode 的集成还会上报智能体的状态。在它们上报期间,Herdr 使用这些上报,而不是读取屏幕。其他集成则把状态交给屏幕检测。
+Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI 和 MastraCode 的集成还会上报智能体的状态。在它们上报期间,Herdr 使用这些上报,而不是读取屏幕。Codex 使用 `--no-daemon` 运行时会上报轮次状态,可见的阻塞提示仍由屏幕检测处理。其他集成则把状态交给屏幕检测。

 原生会话恢复需要最新的 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`、Qwen Code 版本 `1`、Letta Code 版本 `1`、Cursor Agent CLI 版本 `1`、Grok CLI 版本 `2`、OpenCode 版本 `5`、Kilo Code CLI 版本 `1`、Hermes Agent 版本 `5`、MastraCode 版本 `1`、Antigravity CLI 版本 `1`。用 `herdr integration status` 查看已安装版本。

@@ -125,7 +125,7 @@ Herdr 默认使用 `~/.claude`,设置了 `CLAUDE_CONFIG_DIR` 时使用后者。C
 herdr integration install codex
 ```

-Codex 钩子通过与其他集成相同的本地 socket API 上报会话身份。Codex 的状态来自 Herdr 的屏幕清单检测。
+Codex 使用 `--no-daemon` 运行时,钩子通过本地 socket API 上报会话身份和轮次开始／停止状态。屏幕检测仍处理可见的阻塞提示,并在钩子不可用时补充状态。共享的 Codex 守护进程可能把钩子发到错误的窗格,因此请使用 `--no-daemon` 获得可靠的上报;仅禁用自动启动不会停止已经运行的守护进程。

 Herdr 默认使用 `~/.codex`,设置了 `CODEX_HOME` 时使用后者。Codex 配置目录必须已经存在。安装会写入 `herdr-agent-state.sh`、更新 `hooks.json`,并确保 `config.toml` 中有 `[features] hooks = true`。如果存在已弃用的顶层 `codex_hooks` 标志,它也会一并移除。卸载会从 `hooks.json` 中移除 Herdr 条目并删除钩子脚本,但不改动 `config.toml`。

@@ -64,6 +64,12 @@ Herdr 是鼠标原生的。你可以点击窗格、标签页、工作区和智

 Goto 选择器 (`prefix+g`) 按工作区分组，每个代理或终端各占一行，分割标签页中的窗格也会直接显示。点击一行或按回车即可跳转到对应窗格。按 `/` 搜索名称、代理类型、标签页、工作区、分支或路径；未输入搜索时，用上下方向键或 `j/k` 在各行之间移动，左右方向键跳到上一个或下一个工作区中的第一个代理或终端，到达两端后不会循环。编辑搜索内容时，左右方向键只移动文本光标。用 `b/w/i/d` 筛选 blocked、working、idle 或 done 状态的代理，按 `a` 重新显示所有终端。所选目标的位置和路径显示在列表下方。列表超出可视区域时，可以使用鼠标滚轮、点击滚动条轨道或拖动滑块来滚动，而不会打开目标。

+按 Esc 或 Ctrl+[ 退出工作区导航。在 Go To 中,即使布局需要 Shift 才能输入 `/`,也可以用它打开搜索。
+
+窗格输入遵循应用请求的键盘模式。普通 shell 将 Ctrl+Shift+字母作为控制字节接收;窗格无法表示的 Super、Hyper 和 Meta 组合键会被丢弃。使用 Kitty 键盘输入的应用会收到其请求的修饰键和按键事件。非 report-all 模式下,带修饰键的 Enter、Tab 和 Backspace 不接收释放报告。数字小键盘键和单独的修饰键按下也不会转发。
+
+非拉丁布局中,Ctrl+W 等仅带 Ctrl 的快捷键可以使用支持 Kitty 的主终端报告的物理基础键。拉丁布局字符、Ctrl+Shift 和 AltGr 保留布局含义。不报告物理键的终端无法提供相同的跨布局快捷键。
+
 ## 编辑文本输入框

 Herdr 的命名对话框、worktree 分支名、筛选框和复制模式搜索框支持在光标处编辑。以下快捷键适用于 Herdr 自己的输入框，不改变窗格内 shell 或智能体的按键行为。
@@ -13,6 +13,8 @@ Herdr 让窗格在后台服务器中持续运行。你的终端客户端可以

 在服务器完全停止后再次启动时,Herdr 会恢复保存的会话形态。关于分离、服务器重启、屏幕历史回放、智能体原生会话恢复和实时交接各自能保留什么,参见[会话状态与恢复](/zh-cn/docs/session-state/)。

+在 Linux 和 macOS 上,服务器忽略 `SIGHUP`,因此启动它的 shell 挂断不会停止窗格。要主动停止服务器,请使用 `herdr server stop` 或 `SIGTERM`;原先使用 `SIGHUP` 的脚本需要修改。关闭日志会记录停止原因。
+
 ## 命名会话

 需要相互独立的 Herdr 服务器时,使用命名会话。
@@ -158,6 +158,7 @@ PowerShell、Python、Rust、Go、Lua、Bun 或用户机器上可用的任何其

 ```bash
 herdr plugin install ogulcancelik/herdr-plugin-examples/agent-telegram-notify
+herdr plugin update
 herdr plugin config-dir examples.agent-telegram-notify
 herdr plugin list
 herdr plugin action list --plugin examples.agent-telegram-notify
@@ -175,9 +176,13 @@ herdr plugin log list --plugin example.layout
 ```

 `plugin install` 只接受 GitHub 简写,比如 `owner/repo/subdir`。它用 `git`
-克隆,在交互式终端展示预览,运行受支持的构建命令,然后把检出保存到
-Herdr 管理的插件数据下并注册。非交互式安装用 `--yes`。重新安装 GitHub
-管理的插件会替换该托管检出。已安装和已链接的插件及其启用状态对当前用户
+克隆,在交互式终端展示预览,在新的 Herdr 托管安装目录中构建并注册。
+非交互式安装用 `--yes`。更新和重新安装会保留旧安装:运行中的命令和窗格继续
+使用原来的文件,新调用无需重新加载配置便会使用新版本。现有进程不会重启,
+启动钩子仍在下次服务器启动时运行。
+`plugin update` 不指定目标时更新所有 GitHub 托管插件,也可以指定插件 id 或 GitHub 来源。
+它重新获取安装时记录的 ref,跳过未变化的提交,批量更新时忽略本地链接的插件。
+非交互式更新用 `--yes`。已安装和已链接的插件及其启用状态对当前用户
 全局生效,可在所有 Herdr 会话中使用。即使 Herdr 服务器没有运行,也可以通过
 `plugin install` 和 `plugin link` 注册插件。仅安装在 Herdr 0.7.3 命名会话中的
 插件必须重新 install 或 link;现有的插件配置和状态会保留。
@@ -186,11 +191,14 @@ Herdr 管理的插件数据下并注册。非交互式安装用 `--yes`。重新
 插件的配置和状态目录,`plugin config-dir <id>` 打印配置目录,方便安装
 文档和 shell 脚本使用。

-`plugin uninstall <id-or-source>` 注销插件。对 GitHub 管理的安装,它还会
-删除托管检出,并且既接受插件 id,也接受与 install 相同的
-`owner/repo[/subdir...]` 简写。`plugin unlink <id>` 只注销插件、不动文件,
-对本地开发很有用。v1 没有单独的 `plugin update`;要刷新托管插件,请从
-GitHub 重新安装。
+`plugin uninstall <id-or-source>` 注销插件,接受插件 id 或与 install 相同的
+`owner/repo[/subdir...]` 简写。更新、重新安装和卸载后会保留安装文件,
+让运行中的插件完成工作。使用旧安装的服务器退出后,下一次成功安装、更新或
+服务器启动会自动清理过时的托管安装。重新加载配置不会释放旧安装。
+关闭服务器前请停止插件工作;服务器退出后仍存活的进程不受清理保护。
+插件必须在其父命令或窗格退出前停止分离的后台进程。
+没有清理跟踪的旧安装会保留,配置和状态也会保留。
+`plugin unlink <id>` 只注销插件、不动文件,对本地开发很有用。

 示例菜谱仓库是 `ogulcancelik/herdr-plugin-examples`。它在子目录中包含
 多个独立示例插件,包括 `agent-telegram-notify`、`github-link-preview` 和
@@ -49,6 +49,19 @@ Windows 构建同时通过稳定版和预览版更新通道提供。新安装默

 本地持久会话会在客户端分离或终端窗口关闭后继续运行。通过 Windows OpenSSH 启动的服务器和窗格进程也会在注销后继续运行;再次运行 `herdr` 即可重新连接。

+提升权限的 Windows 服务器默认要求管理员客户端,包括通过提升权限的 SSH 登录启动的服务器。普通服务器接受同一账户的普通和管理员客户端;连接不会改变服务器权限。
+
+若要主动与普通客户端共享管理员会话,请设置:
+
+```toml
+[server]
+allow_unelevated_clients = true
+```
+
+此 Windows 专用设置默认关闭,在新服务器启动时生效,包括自动启动。重新加载配置不会改变运行中服务器的访问策略。也可以在管理员终端运行 `herdr server --allow-unelevated-clients`（命名会话使用 `herdr --session <name> server --allow-unelevated-clients`）,只为该服务器进程启用共享。即使配置为 false,此标志仍会启用共享。
+
+两种方式都会允许同一账户的普通本地进程控制管理员窗格;其他账户仍被排除。除非配置中已启用共享,否则重启后必须再次指定标志。现有服务器在停止并用更新版本重启前保持原来的访问策略;停止会关闭窗格。配置和恢复文件仍保留基于账户的权限。
+
 Windows 智能体进程检测会扫描窗格 shell 的后代进程,识别直接运行的智能体和常见的命令包装器,包括 npm/Node 和 Git Bash 进程链。它会跨越模拟的 `exec` 边界跟踪从 Git Bash 启动的智能体,但这和 Unix 前台进程组检测不是一回事。

 Windows 目前支持安装 Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、OpenCode、Kilo Code CLI、Droid、Kimi Code CLI、Qoder CLI 和 Antigravity CLI 集成。可用范围比 Unix 更窄;安装格式不受 Windows 支持的集成会被隐藏或拒绝。
@@ -113,6 +126,8 @@ Herdr 的窗格文本复制在 Windows 上可用。在窗格内拖选文本即

 文本粘贴请在 Windows Terminal 中使用 `ctrl+shift+v`。多行文本粘贴是带括号的 (bracketed),因此 shell 和智能体提示符会把它作为一次粘贴接收,而不是逐行提交。按住 `shift` 再右键,可以使用外层终端的粘贴操作,而不把点击发给 Herdr。

+如果 WezTerm 用原始粘贴标记包住完整的 Win32 字符按下／释放记录对,Windows 客户端也能恢复其中的文本。此兼容规则不会解码混合文本或不完整记录。仅包含完整匹配 Win32 记录的字面剪贴板文本无法与这种编码区分,也会被解码。
+
 ## Windows 不支持

 | 能力 | 状态 |
@@ -48,6 +48,8 @@ Only report when `HERDR_ENV=1` and the other variables are set. Outside Herdr, y
 - `--source` identifies your integration. Keep it stable and unique. Don't start it with `herdr:`, because Herdr's own integrations use that prefix.
 - `--seq` is optional but recommended. It must increase with every report from your source, including across sessions and restarts of your agent. A timestamp works well. Herdr ignores reports whose number is not higher than the last one it accepted, so late or out-of-order reports can't overwrite newer state.

+To change how your agent appears without changing its state, such as a title or custom status text, see [Custom status labels](/docs/integrations/#custom-status-labels).
+
 ## Report the resume command

 Put the command that resumes the current session after `--`. Include the options that session needs, such as the model or permission mode, so the resumed session behaves the same:
@@ -90,7 +92,7 @@ If your agent exits without releasing, Herdr notices once the pane is back at it

 - Don't let Herdr slow your agent down. Send reports in the background or with a short timeout, and ignore failures.
 - Send only the latest state. If several changes queue up while a report is in flight, drop the older ones.
- Resume commands need Herdr 0.10.0 or later. Older versions ignore them, so state reports and release keep working there.
+- Resume commands need Herdr 0.9.2 or later. Older versions ignore them, so state reports and release keep working there.

 ## Use the socket directly

@@ -110,9 +112,3 @@ To test restore without touching your normal session, use a separate named sessi
 1. Start `herdr --session my-agent-test`, then run your agent in a pane.
 2. Stop that session with `herdr session stop my-agent-test`.
 3. Start `herdr --session my-agent-test` again. The pane should run your resume command and your agent should report again.
-
-## Example
-
-[Prime Agent's built-in Herdr reporter](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.ts) is a real-world integration. It activates only inside Herdr, maps agent events to `working`, `idle`, and `blocked`, keeps its report order across sessions, and releases the pane on exit.
-
-To change how your agent appears without changing its state, such as a title or custom status text, see [Custom status labels](/docs/integrations/#custom-status-labels).
@@ -47,10 +47,13 @@ Herdr recognizes these agents and reads their state from what they draw on scree

 These agents report their own state to Herdr. There is nothing to install; run them in a Herdr pane.

- [Crush](https://github.com/charmbracelet/crush)
- Command Code
- Muse
- [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent)
+<ul class="agent-logos">
+  <li><a href="https://commandcode.ai"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/command-code.svg')" }} aria-hidden="true"></span>Command Code</a></li>
+  <li><a href="https://github.com/charmbracelet/crush"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/crush.svg')" }} aria-hidden="true"></span>Crush</a></li>
+  <li><a href="https://kiro.dev/cli/"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/kiro-mask.svg')" }} aria-hidden="true"></span>Kiro CLI</a></li>
+  <li><a href="https://dev.meta.ai/products/muse-code"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/muse-code.svg')" }} aria-hidden="true"></span>Muse Code</a></li>
+  <li><a href="https://github.com/PrimeIntellect-ai/prime-agent"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/prime-agent.svg')" }} aria-hidden="true"></span>Prime Agent</a></li>
+</ul>

 An agent that also reports its resume command comes back in the same session after a Herdr server restart.

@@ -70,11 +73,9 @@ Some restricted Linux runtimes do not expose a terminal foreground process group

 ## Blocked state

-Blocked detection is deliberately strict for screen-manifest agents. Herdr only marks `blocked` when the live bottom-buffer snapshot matches known visible approval, question, or permission UI. If no manifest rule matches for a known agent other than Codex, Herdr falls back to `idle` and labels that fallback as `default_known_agent_idle_fallback` in explain output. Codex falls back to `unknown` because its title and composer can look the same during an active turn and after a response.
+Blocked detection is deliberately strict for screen-manifest agents. Herdr only marks `blocked` when the live bottom-buffer snapshot matches known visible approval, question, or permission UI. If no manifest rule matches for a known agent, Herdr falls back to `idle` and labels that fallback as `default_known_agent_idle_fallback` in explain output.

-For those other agents, unusual new prompts may initially show as `idle` instead of `blocked` until Herdr learns that screen shape. The misclassification affects only the visible status and waits. It should not make Herdr send input or take destructive action.
-
-For Codex, a visible spinner or live activity timer can establish `working`, and a visible approval prompt can establish `blocked`. An ordinary title, composer, or missing spinner cannot establish that a turn ended. Codex may therefore stay `unknown` after a response, and waits for `idle` or completion may time out. Managed startup uses the initial composer only to determine when it can accept a prompt; that observation does not change turn status.
+This means unusual new agent prompts may initially show as `idle` instead of `blocked` until Herdr learns that screen shape. The misclassification affects only the visible status and waits. It should not make Herdr send input or take destructive action.

 ## Detection manifests

@@ -198,7 +198,7 @@ herdr tab close <tab_id>

 A tab is another terminal layout inside a workspace. Without `--workspace`, `tab create` uses the active workspace and fails if none exists. Its JSON response exposes `.result.tab.tab_id` and `.result.root_pane.pane_id`. Closing a workspace's last tab also closes the workspace, matching the TUI close-tab action. If `confirm_close` is enabled and closing the tab would also close a whole worktree group, `tab close` returns a `confirmation_required` error instead.

-With `ui.confirm_close` enabled, the TUI asks for confirmation before closing a workspace's last tab from a keybinding or the tab menu. Ordinary CLI/API tab closes remain immediate.
+With `ui.confirm_close` enabled, the TUI asks for confirmation before closing a workspace's last tab or its only pane from a keybinding or the tab/pane menu. Ordinary pane closes and CLI/API closes remain immediate.

 Workspace and tab creation, and pane splitting, leave focus unchanged by default. `--focus` selects the new layout; `--no-focus` states the default explicitly. Without `--cwd`, new terminals follow the configured `terminal.new_cwd` policy, which follows the source pane or workspace by default. Each `--env KEY=VALUE` adds or replaces that variable in the new root shell.

@@ -466,13 +466,14 @@ Install, list, and remove plugins:

 ```bash
 herdr plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]
+herdr plugin update [<plugin_id|owner/repo[/subdir...]>...] [--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` accepts GitHub shorthand only, such as `ogulcancelik/herdr-plugin-examples/worktree-bootstrap`. It uses `git`, shows a trust preview in interactive terminals, runs supported manifest build commands, and stores GitHub installs in a Herdr-managed directory. Use `--yes` for noninteractive installs. Reinstalling a GitHub-managed plugin replaces that managed checkout. Installing over a locally linked plugin is refused. Plugin manifests must declare `min_herdr_version`; install and link fail when the plugin requires a newer Herdr binary. `plugin list` is human-readable by default; pass `--json` for the raw API response.
+`plugin install` accepts GitHub shorthand only, such as `ogulcancelik/herdr-plugin-examples/worktree-bootstrap`. It uses `git`, shows a trust preview in interactive terminals, runs supported manifest build commands, and stores GitHub installs in a Herdr-managed directory. Use `--yes` for noninteractive installs. `plugin update` refreshes every GitHub-managed plugin when no targets are given, or only the listed plugin ids or GitHub sources. It preserves each install's requested ref, skips unchanged commits and ignores locally linked plugins during bulk updates. Reinstalling a GitHub-managed plugin creates a new installation directory. Running plugins keep their original files; new invocations use the new installation. Installing over a locally linked plugin is refused. Plugin manifests must declare `min_herdr_version`; install and link fail when the plugin requires a newer Herdr binary. `plugin list` is human-readable by default; pass `--json` for the raw API response.

 Plugin installation and enabled state are global to the current user. A plugin installed, linked, enabled, or disabled through one Herdr session is immediately available with the same state in every session.

@@ -483,7 +484,7 @@ herdr plugin link <path> [--disabled]
 herdr plugin unlink <plugin_id>
 ```

-`plugin link` accepts a plugin directory containing `herdr-plugin.toml` or a direct manifest path. Use it while authoring or testing a plugin from a local checkout. `plugin unlink` unregisters the plugin and leaves files alone. `plugin uninstall` unregisters a plugin and also removes Herdr-managed GitHub checkout files. For GitHub installs, uninstall accepts either the plugin id or the same `owner/repo[/subdir...]` shorthand used by install. Actions, event hooks, panes, and link handlers are declared in the manifest; runtime action registration is not part of v1.
+`plugin link` accepts a plugin directory containing `herdr-plugin.toml` or a direct manifest path. Use it while authoring or testing a plugin from a local checkout. `plugin unlink` and `plugin uninstall` unregister the plugin and leave files in place so running plugins can finish. Updates and reinstalls also retain previous installations; new invocations use the replacement without a config reload. A later successful installation/update or server startup removes obsolete managed installations after the servers using them have exited. Config reload does not release old installations. Plugins must stop detached background processes before their parent command or pane exits; processes surviving server exit are not protected from cleanup. Legacy installations without cleanup tracking and locally linked files are retained. For GitHub installs, uninstall accepts either the plugin id or the same `owner/repo[/subdir...]` shorthand used by install. Actions, event hooks, panes, and link handlers are declared in the manifest; runtime action registration is not part of v1.

 Config directory:

@@ -533,6 +534,8 @@ in pane or agent APIs. Native non-terminal plugin panes are outside plugin v1.

 New panes identify as `TERM_PROGRAM=herdr`, with `TERM_PROGRAM_VERSION` set to
 Herdr's version. They keep `TERM=xterm-256color` and `COLORTERM=truecolor`.
+They also get `fish_handle_reflow=0`, because Herdr reflows text on resize;
+an inherited or explicit `fish_handle_reflow` value is kept.
 Herdr removes inherited outer-terminal session markers (iTerm2, WezTerm, Kitty,
 Windows Terminal, tmux, screen, and Zellij), iTerm2's `LC_TERMINAL` identity,
 and known Claude Code, Codex, and OMP session markers before applying explicit
@@ -496,6 +496,8 @@ Choose `herdr` for an in-app toast, `terminal` for an outer-terminal notificatio

 On macOS, `system` tries `terminal-notifier` first and falls back to `/usr/bin/osascript` when it is unavailable or fails. The fallback appears as Script Editor in Notification Center and cannot activate the hosting terminal. Install `terminal-notifier` with `brew install terminal-notifier`. For a supported, detected terminal, it can activate the terminal app when you click the notification. Alternatively, choose `terminal` to let a supported outer terminal own the notification.

+On Windows, `system` notifications remain in Notification Center. Clicking one selects its originating pane in the running Herdr client and brings its terminal window forward when Windows exposes that window. A click cannot reopen a closed client or select a pane from a restarted server. Windows Terminal can bring the owning window forward, but cannot reliably select a different outer terminal tab.
+
 ## Sound

 Sound notifications play through the local Herdr client. Custom sounds must be mp3 files; Herdr resolves relative paths from the config file's directory.
@@ -59,7 +59,7 @@ Herdr saves integration configs atomically on Linux/macOS and for new files; exi

 Every integration tells Herdr which session the agent is in, so Herdr can resume it after a server restart. Turn this off with `[session] resume_agents_on_restore = false`.

-The Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, and MastraCode integrations also report the agent's state. While they report, Herdr uses them instead of reading the screen. The others leave state to screen detection.
+The Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, and MastraCode integrations also report the agent's state. While they report, Herdr uses them instead of reading the screen. Codex reports turn state when run with `--no-daemon`; screen detection still handles its visible blockers. Other integrations leave state to screen detection.

 Native session restore requires current Herdr integrations: Pi integration version `2`, OMP version `3`, Claude Code version `6`, Codex version `5`, GitHub Copilot CLI version `2`, Devin CLI version `2`, Droid version `2`, Kimi Code CLI version `3`, Qoder CLI version `2`, Qwen Code version `1`, Letta Code version `1`, Cursor Agent CLI version `1`, Grok CLI version `2`, OpenCode version `5`, Kilo Code CLI version `1`, Hermes Agent version `5`, MastraCode version `1`, or Antigravity CLI version `1`. Check installed versions with `herdr integration status`.

@@ -123,7 +123,7 @@ Install the Codex hook:
 herdr integration install codex
 ```

-The Codex hook reports session identity through the same local socket API used by other integrations. Codex state comes from Herdr's screen manifest detection.
+When Codex runs with `--no-daemon`, the hook reports session identity and turn start/stop state through Herdr's local socket API. Screen detection still handles visible blockers and fills gaps when hooks are unavailable. A shared Codex daemon can route hooks to the wrong pane, so use `--no-daemon` for reliable reports; disabling daemon auto-start alone does not stop an existing daemon.

 Herdr uses `~/.codex` by default, or `CODEX_HOME` when set. The Codex config directory must already exist. Install writes `herdr-agent-state.sh`, updates `hooks.json`, and ensures `[features] hooks = true` in `config.toml`. It also removes the deprecated top-level `codex_hooks` flag when present. Uninstall removes Herdr entries from `hooks.json` and deletes the hook script, but leaves `config.toml` unchanged.

@@ -48,6 +48,8 @@ Herdr ペイン内のすべてのプロセスは、次の環境変数を継承
 - `--source` はインテグレーションを識別します。固定かつ一意にしてください。`herdr:` で始めないでください。この接頭辞は Herdr 自身のインテグレーションが使います。
 - `--seq` は省略できますが、付けることを推奨します。source からの報告ごとに増加する必要があり、エージェントのセッションや再起動をまたいでも増加し続ける必要があります。タイムスタンプが適しています。Herdr は最後に受け付けた番号より大きくない報告を無視するので、遅れて届いた報告や順不同の報告が新しい状態を上書きすることはありません。

+タイトルやカスタムのステータス文言など、状態を変えずにエージェントの見た目を変えるには、[カスタムステータスラベル](/ja/docs/integrations/#カスタムステータスラベル)を参照してください。
+
 ## resume コマンドを報告する

 現在のセッションを再開するコマンドを `--` の後に置きます。モデルや権限モードなど、そのセッションに必要なオプションも含めると、再開したセッションが同じように動きます:
@@ -90,7 +92,7 @@ Herdr サーバーの再起動後、Herdr は同じディレクトリでペイ

 - Herdr のせいでエージェントを遅くしないでください。報告はバックグラウンドか短いタイムアウトで送り、失敗は無視します。
 - 最新の状態だけを送ります。報告の送信中に複数の変化がたまったら、古いものは捨てます。
- resume コマンドには Herdr 0.10.0 以降が必要です。古いバージョンはこれを無視するので、状態の報告と解放はそのまま動きます。
+- resume コマンドには Herdr 0.9.2 以降が必要です。古いバージョンはこれを無視するので、状態の報告と解放はそのまま動きます。

 ## ソケットを直接使う

@@ -110,9 +112,3 @@ herdr agent list
 1. `herdr --session my-agent-test` を起動し、ペインでエージェントを実行します。
 2. `herdr session stop my-agent-test` でそのセッションを停止します。
 3. `herdr --session my-agent-test` をもう一度起動します。ペインで resume コマンドが実行され、エージェントが再び報告するはずです。
-
-## 例
-
-[Prime Agent の組み込み Herdr レポーター](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.ts)は実際のインテグレーションです。Herdr 内でのみ有効になり、エージェントイベントを `working`、`idle`、`blocked` に対応付け、セッションをまたいで報告順序を維持し、終了時にペインを解放します。
-
-タイトルやカスタムのステータス文言など、状態を変えずにエージェントの見た目を変えるには、[カスタムステータスラベル](/ja/docs/integrations/#カスタムステータスラベル)を参照してください。
@@ -47,10 +47,13 @@ Herdr はこれらのエージェントを認識し、画面の表示から状

 これらのエージェントは自分の状態を Herdr に報告します。インストールするものはありません。Herdr のペインで実行するだけです。

- [Crush](https://github.com/charmbracelet/crush)
- Command Code
- Muse
- [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent)
+<ul class="agent-logos">
+  <li><a href="https://commandcode.ai"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/command-code.svg')" }} aria-hidden="true"></span>Command Code</a></li>
+  <li><a href="https://github.com/charmbracelet/crush"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/crush.svg')" }} aria-hidden="true"></span>Crush</a></li>
+  <li><a href="https://kiro.dev/cli/"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/kiro-mask.svg')" }} aria-hidden="true"></span>Kiro CLI</a></li>
+  <li><a href="https://dev.meta.ai/products/muse-code"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/muse-code.svg')" }} aria-hidden="true"></span>Muse Code</a></li>
+  <li><a href="https://github.com/PrimeIntellect-ai/prime-agent"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/prime-agent.svg')" }} aria-hidden="true"></span>Prime Agent</a></li>
+</ul>

 resume コマンドも報告するエージェントは、Herdr サーバーの再起動後に同じセッションで戻ります。

@@ -70,11 +73,9 @@ Linux と macOS では、ホストから見えるラッパーが実際のエー

 ## blocked 状態

-スクリーンマニフェスト方式のエージェントでは、blocked の検出は意図的に厳格です。Herdr が `blocked` と判定するのは、ライブの下部バッファスナップショットが既知の承認・質問・許可 UI にマッチしたときだけです。Codex 以外の既知エージェントでどのマニフェストルールにもマッチしない場合、Herdr は `idle` にフォールバックし、explain の出力ではそのフォールバックに `default_known_agent_idle_fallback` というラベルを付けます。Codex は、タイトルとコンポーザーがアクティブなターン中と応答後で同じに見える場合があるため、`unknown` にフォールバックします。
+スクリーンマニフェスト方式のエージェントでは、blocked の検出は意図的に厳格です。Herdr が `blocked` と判定するのは、ライブの下部バッファスナップショットが既知の承認・質問・許可 UI にマッチしたときだけです。既知のエージェントでどのマニフェストルールにもマッチしない場合、Herdr は `idle` にフォールバックし、explain の出力ではそのフォールバックに `default_known_agent_idle_fallback` というラベルを付けます。

-それら Codex 以外のエージェントでは、見慣れない新しいプロンプトが、Herdr がその画面の形を学習するまで、最初は `blocked` ではなく `idle` と表示されることがあります。誤分類の影響は表示上の状態と wait だけです。これによって Herdr が入力を送ったり破壊的な操作をしたりすることはありません。
-
-Codex では、表示中のスピナーや稼働中のアクティビティタイマーから `working` を、表示中の承認プロンプトから `blocked` を判定できます。通常のタイトルやコンポーザー、スピナーがないことだけでは、ターンの終了を判定できません。そのため、Codex は応答後も `unknown` のままになることがあり、`idle` または完了を待つ処理はタイムアウトする場合があります。管理対象の起動では、初期コンポーザーをプロンプト受付可能になったかの判定にのみ使います。この観測によってターン状態は変わりません。
+つまり、見慣れない新しいエージェントプロンプトは、Herdr がその画面の形を学習するまで、最初は `blocked` ではなく `idle` と表示されることがあります。こうしたやり取りによって Herdr が入力を送ったり破壊的な操作をしたりすることはありません。影響するのは表示上の状態と wait だけです。

 ## 検出マニフェスト

@@ -194,7 +194,7 @@ herdr tab close <tab_id>

 タブはワークスペース内の別のターミナルレイアウトです。`--workspace` を省略すると、`tab create` はアクティブなワークスペースを使い、存在しなければ失敗します。JSON レスポンスの `.result.tab.tab_id` と `.result.root_pane.pane_id` から ID を取得できます。ワークスペースの最後のタブを閉じると、そのワークスペースも閉じられます。`ui.confirm_close` が有効で、親ワークツリーの最後のタブを閉じるとワークツリーグループ全体が閉じられる場合、`tab close` は `confirmation_required` エラーを返します。

-`ui.confirm_close` が有効な場合、キーバインドやタブメニューからワークスペースの最後のタブを閉じる前に、TUI が確認を求めます。通常の CLI/API によるタブの終了は引き続き即座に実行されます。
+`ui.confirm_close` が有効な場合、キーバインドやタブ／ペインメニューからワークスペースの最後のタブ、または唯一のペインを閉じる前に、TUI が確認を求めます。通常のペイン終了や CLI/API による終了は引き続き即座に実行されます。

 ワークスペースとタブの作成、およびペインの分割は、デフォルトではフォーカスを変えません。`--focus` は新しいレイアウトを選択し、`--no-focus` はデフォルトを明示します。`--cwd` がない場合、新しいターミナルは `terminal.new_cwd` の設定に従い、デフォルトでは元のペインまたはワークスペースを引き継ぎます。各 `--env KEY=VALUE` は新しいルートシェルの環境変数を追加または置換します。

@@ -50,6 +50,8 @@ herdr --remote workbox
 herdr --remote ssh://you@server:2222
 ```

+サイドバーの幅、セクションの分割位置、折りたたんだグループ、エージェントの並び順は、接続先とセッションごとにローカルへ保存されます。同じ接続先とセッションに再接続すると復元されます。SSH エイリアスやセッションが異なる場合は別の設定になります。
+
 このモードでは、リモートサーバーがペインを動かし、ターミナル内容とセッション状態を SSH 越しに送信します。ローカルの Herdr がサイドバー、メニュー、テーマを含む UI を描画します。クライアントがローカルで動くため、Herdr は画像クリップボードの貼り付けのようなローカルデスクトップ機能をリモートセッションにブリッジできます。画像をリモートの一時ファイルにコピーし、そのパスを貼り付けます。

 デフォルトでは、`herdr --remote` はそのアタッチにローカルの Herdr キーバインドを使います。リモートサーバーの設定が異なっていても、ローカルの操作感覚を維持できます。ローカルキーバインドを編集したら、UI の `reload config` でデタッチせずに反映できます。リモートサーバーの設定を使いたい場合は `--remote-keybindings server` を使います。ローカルのカスタムコマンドキーバインドは送信されません。それらのコマンドはリモートホスト上で実行されてしまうからです。
@@ -69,7 +71,7 @@ Host workbox
 herdr --remote workbox
 ```

-リモートアタッチと保存済み SSH マシンは、Linux、macOS、Windows のクライアントから、x86_64 または aarch64 の Linux/macOS ホスト、および x86_64 の Windows ホストへの接続に対応します。両端が安定したエンドポイント世代に対応していれば、バージョンは一致しなくても構いません。Linux/macOS ではリモートの `PATH` 上の互換バイナリを優先し、次に一般的な直接インストール、Homebrew、mise、Nix のパスを確認します。Windows では `PATH` と現在有効な管理対象リリースを確認します。互換バイナリがなければ、対話的な実行はインストールや更新の確認を求め、非対話的な実行はホストを変更せず失敗します。Linux/macOS では `~/.local/bin/herdr` に、Windows ではアプリローカル ConPTY ランタイムを含む完全なパッケージをインストールします。リモートの `PATH` に `~/.local/bin` がない場合は警告します。
+リモートアタッチと保存済み SSH マシンは、Linux、macOS、Windows のクライアントから、x86_64 または aarch64 の Linux/macOS ホスト、および x86_64 の Windows ホストへの接続に対応します。Windows ARM64 ホストは、Windows の x64 エミュレーションで x64 ビルドを実行するベストエフォート対応です。不具合や問題が発生する可能性があります。ホストが ARM64 を報告した場合、明示的なリモートアタッチと保存済みマシンのセットアップ時にエミュレーションの注意書きを表示します。両端が安定したエンドポイント世代に対応していれば、バージョンは一致しなくても構いません。Linux/macOS ではリモートの `PATH` 上の互換バイナリを優先し、次に一般的な直接インストール、Homebrew、mise、Nix のパスを確認します。Windows では `PATH` と現在有効な管理対象リリースを確認します。互換バイナリがなければ、対話的な実行はインストールや更新の確認を求め、非対話的な実行はホストを変更せず失敗します。Linux/macOS では `~/.local/bin/herdr` に、Windows ではアプリローカル ConPTY ランタイムを含む完全なパッケージをインストールします。リモートの `PATH` に `~/.local/bin` がない場合は警告します。

 デフォルトでは、`herdr --remote` はユーザーの SSH config を最初に include し、その後にフォールバックのキープアライブ設定を加えた一時的な SSH config を通してリモートセットアップとブリッジを実行します。既存のユーザーのキープアライブ設定が優先されます。Linux と macOS クライアントは接続再利用用のプライベートなアタッチ単位コントロールソケットも使いますが、Windows OpenSSH では使いません。Herdr が生成する設定やコントロールソケットを使わず通常の `ssh` を使うには `[remote].manage_ssh_config = false` を設定してください。

@@ -350,6 +350,8 @@ description = "apply layout"
 シェルプラグインは `HERDR_PLUGIN_CLICKED_URL` と `HERDR_PLUGIN_LINK_HANDLER_ID` も
 読めます。ハンドラーは各プラグイン内でマニフェストの順にチェックされます。

+リンクのクリックでプラグインを呼び出すのは、`ui.mouse_capture` が有効な場合だけです。一致するハンドラーが先に実行され、起動に失敗するとエラーを表示して停止します。一致するハンドラーがない場合、外部で開くのは HTTP(S) リンクだけです。キャプチャが無効な場合、外側のターミナルが通常のショートカットと警告で明示的なハイパーリンクを処理します。Windows Terminal の URL 検出の注意点は[マウス操作](/ja/docs/quick-start/#マウスを使う)を参照してください。
+
 ## ストレージ

 v1 には Herdr が管理するプラグインストレージ API はありません。永続状態が必要な
@@ -19,7 +19,13 @@ Herdr はデフォルトのバックグラウンドセッションを起動す

 Herdr はマウスネイティブなので、まずはクリックから始めてください。ペイン、タブ、ワークスペース、エージェントをクリックしてフォーカスします。分割境界をドラッグしてリサイズします。右クリックでコンテキストメニューが開き、ペインの分割やタブの作成ができます。テキストをドラッグ選択するとクリップボードにコピーされます。トークンをダブルクリックすると選択し、2 回目の押下を保持してドラッグすると単語単位で選択を広げられます。どちらもマウスを離すとコピーされます。コピーに Ctrl+C は不要です。

-ターミナルが修飾キー付きクリックを Herdr に渡す場合、Ctrl+クリックでペイン内のリンクを開けます。OSC 8 ハイパーリンクと `http://` または `https://` の URL に対応し、折り返されたリンクの先頭や末尾が表示範囲外でも開けます。Ctrl を押しながらリンク上にポインターを移動すると、表示中の部分に下線が付きます。ポインターを外す、ペイン内容が変わる、または Ctrl の解放イベントを受け取ると下線は消えます。一部のターミナルでは、修飾キーの変化はマウス移動時にだけ報告されます。macOS では、マウスキャプチャが有効な間は Herdr が処理するペインリンクに Ctrl+クリックを使ってください。Cmd+クリックは Shift+Cmd+クリックや `ui.mouse_capture = false` といったターミナルネイティブのバイパス経路でのみ使えます。
+ターミナルが修飾キー付きクリックを Herdr に渡す場合、Ctrl+クリックでペイン内のリンクを開けます。OSC 8 ハイパーリンクと `http://` または `https://` の URL に対応し、折り返されたリンクの先頭や末尾が表示範囲外でも開けます。Ctrl を押しながらリンク上にポインターを移動すると、表示中の部分に下線が付きます。ポインターを外す、ペイン内容が変わる、または Ctrl の解放イベントを受け取ると下線は消えます。一部のターミナルでは、修飾キーの変化はマウス移動時にだけ報告されます。
+
+`ui.mouse_capture = true`（既定値）では、Herdr が Ctrl+クリックを処理します。有効なプラグインがリンクに一致すると、先に実行されます。ハンドラーの起動に失敗するとエラーを表示して停止します。一致しない `http://` と `https://` のリンクは、Herdr クライアントが動くマシンの既定ブラウザーで開きます。その他のリンクには一致するプラグインが必要です。このモードでは明示的なハイパーリンクを外側のターミナルに渡さないため、ラベル付きリンクをネイティブ操作で開けません。macOS の Command+クリックも同様です。
+
+`ui.mouse_capture = false` では、明示的なハイパーリンクを外側のターミナルに渡します。そのターミナルの通常のショートカットと警告が使われ、Herdr のプラグインは実行されません。キャプチャを無効にすると、タブのクリックや分割境界のドラッグなど、Herdr のマウス操作も無効になります。
+
+Windows Terminal は表示テキストから検出した URL を先に開く場合があります。それらを確実にプラグインへ渡すには、Windows Terminal の `settings.json` で `"experimental.detectURLs": false` を設定してください。全プロファイルに適用されます。Herdr はこの設定を変更しません。

 `ui.right_click_passthrough_modifier` を設定すると、その修飾キー + 右クリックで、右クリック・ホールド・ドラッグのジェスチャーがマウスレポーティング対応のペインアプリに送られます。

@@ -119,6 +119,8 @@ CLI の `herdr api snapshot` は、クライアントやエージェントが簡

 `pane.send_keys` と `pane.send_input.keys` は Herdr のキーコンボ文字列を受け付けます: 通常の印字可能キー、`enter` や `esc` のような特殊キー、`ctrl+h`、`control+j`、`alt+x`、`shift+tab` のような修飾キーコード、`f1` のようなファンクションキー、`minus` や `plus` のような名前付き記号です。`prefix+` のバインド文字列は受け付けません。

+macOS では、`pane.send_input`（`pane run` が使用）と `agent.start` は、コマンドを入力キューに受け入れる前に、ターミナルの現在のカノニカルモードの入力上限を確認します。Enter を含むエンコード済みの行が上限を超える場合、入力全体を拒否します。シェルプロンプトが表示されてから再試行してください。複数の短い行と raw モードの入力は引き続き使用できます。成功応答はキューへの受け入れを示し、コマンドの実行完了を意味しません。この確認は今回の送信だけを対象とし、以前の未完了行を検査したり、キューで待機中にターミナルモードが変わらないことを保証したりするものではありません。
+
 ```json
 {"id":"req_current","method":"pane.current","params":{"caller_pane_id":"w1:p1"}}
 {"id":"req_layout","method":"pane.layout","params":{"pane_id":"w1:p1"}}
@@ -50,6 +50,8 @@ herdr --remote workbox
 herdr --remote ssh://you@server:2222
 ```

+Sidebar width, section split, collapsed groups, and agent sorting are saved locally for each remote target and session. Reattaching to the same target and session restores these preferences. Different SSH aliases or sessions have separate preferences.
+
 In this mode, the remote server owns the running panes and sends their terminal content and session state over SSH. Your local Herdr draws the UI, including its sidebar, menus, and theme. Because the client runs locally, Herdr can bridge local desktop features such as image clipboard paste into the remote session by copying the image to a remote temp file and pasting that path.

 By default, `herdr --remote` uses your local Herdr keybindings for that attach. This keeps local muscle memory even when the remote server has different config. After editing local keybindings, use the UI's `reload config` action to apply them without detaching. Use `--remote-keybindings server` when you want the remote server config instead. Local custom command keybindings are not sent, because those commands would run on the remote host.
@@ -69,7 +71,7 @@ Then attach with:
 herdr --remote workbox
 ```

-Remote attach and saved SSH machines support Linux, macOS, and Windows local clients connecting to Linux or macOS hosts on x86_64 and aarch64, or Windows hosts on x86_64. Local and remote versions do not need to match once both support the stable endpoint generation. On Linux and macOS hosts, Herdr prefers a compatible `herdr` already on the remote `PATH`, then checks common direct, Homebrew, mise, and Nix profile install paths. On Windows hosts, Herdr checks `PATH` and the active managed release. If no compatible binary exists, interactive runs prompt to install or update one; non-interactive runs fail instead of modifying the host. Linux and macOS installs use `~/.local/bin/herdr`; Windows installs use the complete Windows package and its app-local ConPTY runtime. If `~/.local/bin` is not on the remote `PATH`, Herdr warns after install.
+Remote attach and saved SSH machines support Linux, macOS, and Windows local clients connecting to Linux or macOS hosts on x86_64 and aarch64, or Windows hosts on x86_64. Windows ARM64 hosts are supported on a best-effort basis using the x64 build under Windows emulation; bugs and issues are expected. Explicit remote attach and saved-machine setup display an emulation note when the host reports ARM64. Local and remote versions do not need to match once both support the stable endpoint generation. On Linux and macOS hosts, Herdr prefers a compatible `herdr` already on the remote `PATH`, then checks common direct, Homebrew, mise, and Nix profile install paths. On Windows hosts, Herdr checks `PATH` and the active managed release. If no compatible binary exists, interactive runs prompt to install or update one; non-interactive runs fail instead of modifying the host. Linux and macOS installs use `~/.local/bin/herdr`; Windows installs use the complete Windows package and its app-local ConPTY runtime. If `~/.local/bin` is not on the remote `PATH`, Herdr warns after install.

 By default, `herdr --remote` runs remote setup and the bridge through a temporary SSH config that includes your SSH config first, then adds fallback keepalive settings. Existing user keepalive settings win. Linux and macOS clients also use a private per-attach control socket for connection reuse; Windows OpenSSH does not. Set `[remote].manage_ssh_config = false` to use plain `ssh` without Herdr's generated config or control socket.

@@ -172,6 +172,7 @@ Install an example plugin:

 ```bash
 herdr plugin install ogulcancelik/herdr-plugin-examples/agent-telegram-notify
+herdr plugin update
 herdr plugin config-dir examples.agent-telegram-notify
 herdr plugin list
 herdr plugin action list --plugin examples.agent-telegram-notify
@@ -190,9 +191,16 @@ herdr plugin log list --plugin example.layout

 `plugin install` accepts GitHub shorthand only, such as
 `owner/repo/subdir`. It clones with `git`, shows a preview in interactive
-terminals, runs supported build commands, then stores the checkout under
-Herdr-managed plugin data and registers it. Use `--yes` for noninteractive
-installs. Reinstalling a GitHub-managed plugin replaces that managed checkout.
+terminals, builds in a new Herdr-managed installation directory, and registers
+it. Use `--yes` for noninteractive installs. Updates and reinstalls leave the
+previous installation in place: running commands and panes keep their original
+files, while new invocations use the new installation without a config reload.
+Existing processes are not restarted, and startup hooks run at the next server
+startup as usual.
+`plugin update` refreshes every GitHub-managed plugin when called without a
+target, or only the listed plugin ids or GitHub sources. It refetches the ref
+recorded during install, skips unchanged commits, and ignores locally linked
+plugins during bulk updates. Use `--yes` for noninteractive updates.
 Installed and linked plugins, including their enabled state, are global to the
 current user and available in every Herdr session. Both `plugin install` and
 `plugin link` can register plugins while no Herdr server is running. Plugins
@@ -203,12 +211,18 @@ local plugin first. `plugin install` and `plugin link` create the plugin's
 config and state directories, and `plugin config-dir <id>` prints the config
 directory for setup docs and shell scripts.

-`plugin uninstall <id-or-source>` unregisters the plugin. For GitHub-managed
-installs it also removes the managed checkout, and it accepts either the plugin
-id or the same `owner/repo[/subdir...]` shorthand used by install.
+`plugin uninstall <id-or-source>` unregisters the plugin and accepts either the
+plugin id or the same `owner/repo[/subdir...]` shorthand used by install.
+Installation files are retained after updates, reinstalls, and uninstall so
+running plugins can finish. A later successful installation/update or server
+startup automatically removes obsolete managed installations once the servers
+using them have exited. Reloading config does not release old installations.
+Stop plugin work before shutting down its server: processes surviving server
+exit are not protected from cleanup. Plugins must stop detached background
+processes before their parent command or pane exits. Legacy installations
+without cleanup tracking are retained. Config and state are preserved.
 `plugin unlink <id>` only unregisters a plugin and leaves files alone, which is
-useful for local development. There is no separate `plugin update` in v1;
-reinstall from GitHub to refresh a managed plugin.
+useful for local development.

 The example cookbook repo is `ogulcancelik/herdr-plugin-examples`. It contains
 separate example plugins in subdirectories, including `agent-telegram-notify`,
@@ -354,6 +368,8 @@ name an action declared by the same plugin. Link handler actions receive
 `HERDR_PLUGIN_CLICKED_URL` and `HERDR_PLUGIN_LINK_HANDLER_ID`. Handlers are
 checked in manifest order inside each plugin.

+Link clicks invoke plugins only while `ui.mouse_capture` is enabled. Matching handlers run first. A launch failure shows an error and stops. Without a matching handler, only HTTP(S) links open externally. When capture is disabled, the outer terminal handles explicit hyperlinks using its own shortcuts and warnings. See [mouse controls](/docs/quick-start/#use-the-mouse) for the Windows Terminal URL detection caveat.
+
 ## Storage

 There is no Herdr-managed plugin storage API in v1. Plugins that need durable
@@ -19,7 +19,13 @@ When a session has no workspaces, Herdr opens one automatically. A workspace is

 Herdr is mouse-native, so start by clicking panes, tabs, workspaces, and agents to focus them. Drag split borders to resize. Right-click for context menus, including splitting panes and creating tabs. Drag-select text to copy it to your clipboard. Double-click a token to select it, or hold the second press and drag to extend the selection by whole words. Both gestures copy when you release the mouse. Copying does not require Ctrl+C.

-Ctrl-click opens pane links when your terminal sends the modified click to Herdr. This works for OSC 8 hyperlinks and `http://` or `https://` URLs, including wrapped links whose beginning or end is outside the visible area. Hold Ctrl and move the pointer over a link to underline its visible segments. Hover highlighting clears when you move away, the pane content changes, or Herdr receives a Ctrl-release event; some terminals only report modifier changes with mouse movement. On macOS, use Ctrl-click for Herdr-handled pane links while mouse capture is enabled; Cmd-click is only available through the terminal-native bypass path, such as Shift-Cmd-click or `ui.mouse_capture = false`.
+Ctrl-click opens pane links when your terminal sends the modified click to Herdr. This works for OSC 8 hyperlinks and `http://` or `https://` URLs, including wrapped links whose beginning or end is outside the visible area. Hold Ctrl and move the pointer over a link to underline its visible segments. Hover highlighting clears when you move away, the pane content changes, or Herdr receives a Ctrl-release event; some terminals only report modifier changes with mouse movement.
+
+With `ui.mouse_capture = true` (the default), Herdr handles Ctrl-clicks. Matching enabled plugins run first. A handler launch failure shows an error and stops. Unmatched `http://` and `https://` links open in the default browser on the machine running the Herdr client. Other links need a matching plugin. Explicit hyperlinks are not advertised to the outer terminal in this mode, so native bypass clicks on labeled links are unavailable, including Command-click on macOS.
+
+With `ui.mouse_capture = false`, explicit hyperlinks are passed to the outer terminal. Use its normal link shortcuts and warnings. These clicks do not invoke Herdr plugins. Disabling capture also disables Herdr's mouse controls, including clicking tabs and dragging split borders.
+
+Windows Terminal can still intercept URLs it detects in visible text. For reliable plugin priority on those URLs, set `"experimental.detectURLs": false` in Windows Terminal's `settings.json`. This setting applies to all Windows Terminal profiles. Herdr does not change it.

 If you configure `ui.right_click_passthrough_modifier`, that modifier plus right-click sends right-click, hold, and drag gestures to mouse-reporting pane apps. To make normal right-click go to one pane app, choose **Send right-clicks to pane** from that pane's menu or run `herdr pane input --current --right-click pane` inside it. Right-click the pane frame to reopen Herdr's menu.

@@ -138,6 +138,8 @@ like `ctrl+h`, `control+j`, `alt+x`, and `shift+tab`, function keys like
 `f1`, and named punctuation like `minus` and `plus`. They do not accept
 `prefix+` binding strings.

+On macOS, `pane.send_input` (used by `pane run`) and `agent.start` check the terminal's current canonical input limit before accepting a command into the input queue. An oversized encoded line, including Enter, is rejected in full; wait for the shell prompt and retry. Multiple short lines and raw-mode input remain supported. Successful responses still acknowledge queue admission, not command execution. This check covers the current submission only: it cannot inspect an earlier incomplete line or guarantee the terminal mode will remain unchanged while input is queued.
+
 ```json
 {"id":"req_current","method":"pane.current","params":{"caller_pane_id":"w1:p1"}}
 {"id":"req_layout","method":"pane.layout","params":{"pane_id":"w1:p1"}}
@@ -49,6 +49,19 @@ For internal testing, `HERDR_MANIFEST_URL` can point the installer at a custom m

 Local persistent sessions continue running after the client detaches or its terminal window closes. Servers and pane processes launched through Windows OpenSSH also survive logout; run `herdr` again to reconnect.

+Elevated Windows servers require an administrator client by default, including servers started through an elevated SSH login. Ordinary servers accept clients from ordinary and administrator terminals belonging to the same account; attaching never changes the server's privileges.
+
+To deliberately share elevated sessions with ordinary clients, set:
+
+```toml
+[server]
+allow_unelevated_clients = true
+```
+
+This Windows-only setting is off by default and applies when a new server starts, including automatic startup. Reloading config does not change a running server's access policy. You can instead enable sharing for one server process from an administrator terminal with `herdr server --allow-unelevated-clients` (or `herdr --session <name> server --allow-unelevated-clients` for a named session). The flag enables sharing even when the config setting is false.
+
+Either option allows ordinary local processes belonging to that account to control administrator panes; other accounts remain excluded. The flag must be supplied again after a restart unless sharing is enabled in config. Existing servers retain their previous access policy until stopped and restarted with the updated build; stopping closes their panes. Config and recovery files retain their account-based permissions.
+
 Windows agent process detection scans descendants of the pane shell and recognizes direct agents plus common command wrappers, including npm/Node and Git Bash process chains. It follows Git Bash-launched agents across emulated `exec` boundaries, but it is not the same as Unix foreground process-group detection.

 Windows integration installation currently supports Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, Devin CLI, OpenCode, Kilo Code CLI, Droid, Kimi Code CLI, Qoder CLI, and Antigravity CLI. Availability is narrower than on Unix; Herdr hides or rejects integrations whose install format is not supported on Windows.
@@ -113,6 +126,8 @@ Herdr's pane text copy works on Windows. Drag-select text inside a pane to copy

 For text paste, use `ctrl+shift+v` in Windows Terminal. Multiline text paste is bracketed so shells and agent prompts receive it as one paste instead of submitting each line separately. Hold `shift` and right-click to use the outer terminal paste action instead of sending the click through Herdr.

+Windows clients also recover text when WezTerm wraps a complete sequence of Win32 character press/release pairs in raw paste markers. Mixed text and incomplete reports are not decoded by this compatibility rule. Literal clipboard text consisting entirely of matching Win32 reports is indistinguishable from this encoding and is decoded too.
+
 ## Not supported on Windows

 | Capability | Status |
@@ -48,6 +48,8 @@ Herdr 窗格中的每个进程都会继承这些环境变量:
 - `--source` 用于标识你的集成。保持稳定且唯一。不要以 `herdr:` 开头,这个前缀由 Herdr 自己的集成使用。
 - `--seq` 可以省略,但建议加上。它必须随来自你的来源的每次上报递增,跨会话和智能体重启也要继续递增。时间戳就很合适。Herdr 会忽略编号不大于上次已接受编号的上报,所以迟到或乱序的上报不会覆盖更新的状态。

+如果想在不改变状态的情况下改变智能体的显示方式,例如标题或自定义状态文字,请参阅[自定义状态标签](/zh-cn/docs/integrations/#自定义状态标签)。
+
 ## 上报恢复命令

 把恢复当前会话的命令放在 `--` 之后。带上该会话需要的选项,例如模型或权限模式,这样恢复后的会话行为一致:
@@ -90,7 +92,7 @@ Herdr 服务器重启后,Herdr 会在同一目录中打开该窗格并在其中

 - 不要让 Herdr 拖慢你的智能体。在后台或用较短的超时发送上报,并忽略失败。
 - 只发送最新状态。如果一次上报正在发送时积累了多个变化,丢弃较旧的那些。
- 恢复命令需要 Herdr 0.10.0 或更高版本。旧版会忽略它,状态上报和释放照常工作。
+- 恢复命令需要 Herdr 0.9.2 或更高版本。旧版会忽略它,状态上报和释放照常工作。

 ## 直接使用套接字

@@ -110,9 +112,3 @@ herdr agent list
 1. 启动 `herdr --session my-agent-test`,然后在一个窗格中运行你的智能体。
 2. 用 `herdr session stop my-agent-test` 停止该会话。
 3. 再次启动 `herdr --session my-agent-test`。窗格应当运行你的恢复命令,智能体应当再次上报。
-
-## 示例
-
-[Prime Agent 内置的 Herdr 上报器](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.ts)是一个真实的集成。它只在 Herdr 中启用,将智能体事件映射为 `working`、`idle` 和 `blocked`,跨会话保持上报顺序,并在退出时释放窗格。
-
-如果想在不改变状态的情况下改变智能体的显示方式,例如标题或自定义状态文字,请参阅[自定义状态标签](/zh-cn/docs/integrations/#自定义状态标签)。
@@ -47,10 +47,13 @@ Herdr 能识别这些智能体,并从它们在屏幕上绘制的内容读取状

 这些智能体会自己向 Herdr 上报状态。无需安装任何东西,在 Herdr 窗格中运行即可。

- [Crush](https://github.com/charmbracelet/crush)
- Command Code
- Muse
- [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent)
+<ul class="agent-logos">
+  <li><a href="https://commandcode.ai"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/command-code.svg')" }} aria-hidden="true"></span>Command Code</a></li>
+  <li><a href="https://github.com/charmbracelet/crush"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/crush.svg')" }} aria-hidden="true"></span>Crush</a></li>
+  <li><a href="https://kiro.dev/cli/"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/kiro-mask.svg')" }} aria-hidden="true"></span>Kiro CLI</a></li>
+  <li><a href="https://dev.meta.ai/products/muse-code"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/muse-code.svg')" }} aria-hidden="true"></span>Muse Code</a></li>
+  <li><a href="https://github.com/PrimeIntellect-ai/prime-agent"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/prime-agent.svg')" }} aria-hidden="true"></span>Prime Agent</a></li>
+</ul>

 同时上报恢复命令的智能体,会在 Herdr 服务器重启后回到同一个会话。

@@ -70,11 +73,9 @@ Herdr 能识别这些智能体,并从它们在屏幕上绘制的内容读取状

 ## blocked 状态

-对屏幕清单类智能体,blocked 检测刻意从严。只有当实时底部缓冲区快照匹配已知可见的审批、提问或权限 UI 时,Herdr 才标记 `blocked`。对于 Codex 以外的已知智能体,如果没有任何清单规则匹配,Herdr 会回退到 `idle`,并在 explain 输出中把该回退标记为 `default_known_agent_idle_fallback`。Codex 会回退到 `unknown`,因为在活跃轮次期间和响应结束后,它的标题和输入框可能看起来相同。
+对屏幕清单类智能体,blocked 检测刻意从严。只有当实时底部缓冲区快照匹配已知可见的审批、提问或权限 UI 时,Herdr 才标记 `blocked`。对已知智能体,如果没有任何清单规则匹配,Herdr 会回退到 `idle`,并在 explain 输出中把该回退标记为 `default_known_agent_idle_fallback`。

-对于其他智能体,不常见的新提示可能一开始显示为 `idle` 而不是 `blocked`,直到 Herdr 学会那种屏幕形态。误判只影响可见状态和等待,不会让 Herdr 发送输入或执行破坏性操作。
-
-对于 Codex,可见的旋转指示符或实时活动计时器可以确定 `working`,可见的审批提示可以确定 `blocked`。普通标题、输入框或没有旋转指示符都不能确定一个轮次已经结束。因此,Codex 在响应后可能继续保持 `unknown`,等待 `idle` 或完成也可能超时。托管启动仅使用初始输入框来判断它何时可以接收提示,该观察不会改变轮次状态。
+这意味着不常见的新智能体提示可能一开始显示为 `idle` 而不是 `blocked`,直到 Herdr 学会那种屏幕形态。这些交互不会让 Herdr 发送输入或执行破坏性操作;它们只影响可见状态和等待。

 ## 检测清单

@@ -194,7 +194,7 @@ herdr tab close <tab_id>

 标签页是工作区内的另一个终端布局。不指定 `--workspace` 时,`tab create` 使用活动工作区;如果没有活动工作区则失败。JSON 响应中的 `.result.tab.tab_id` 和 `.result.root_pane.pane_id` 是对应 ID。关闭工作区的最后一个标签页也会关闭该工作区。启用 `ui.confirm_close` 时，如果关闭父工作树的最后一个标签页会连带关闭整个工作树组，`tab close` 会返回 `confirmation_required` 错误。

-启用 `ui.confirm_close` 时，通过快捷键或标签页菜单关闭工作区的最后一个标签页前，TUI 会要求确认。普通的 CLI/API 标签页关闭操作仍立即执行。
+启用 `ui.confirm_close` 时，通过快捷键或标签页／窗格菜单关闭工作区的最后一个标签页或唯一窗格前，TUI 会要求确认。普通的窗格关闭及 CLI/API 关闭操作仍立即执行。

 创建工作区、标签页和拆分窗格默认不改变焦点。`--focus` 选择新布局;`--no-focus` 显式表达默认行为。不指定 `--cwd` 时,新终端遵循 `terminal.new_cwd` 设置,默认跟随来源窗格或工作区。每个 `--env KEY=VALUE` 在新的根 shell 中添加或替换一个环境变量。

@@ -50,6 +50,8 @@ herdr --remote workbox
 herdr --remote ssh://you@server:2222
 ```

+侧栏宽度、分区比例、折叠分组和代理排序会按远程目标与会话保存在本地。重新连接同一目标和会话时会恢复这些偏好；不同 SSH 别名或会话的偏好相互独立。
+
 这种模式下，远程服务器保持窗格运行，并通过 SSH 发送终端内容和会话状态。本地 Herdr 负责绘制 UI，包括侧边栏、菜单和主题。因为客户端在本地运行,Herdr 可以把图像剪贴板粘贴等本地桌面功能桥接到远程会话: 把图像复制到远程临时文件,再粘贴该路径。

 默认情况下,`herdr --remote` 在这次连接中使用你本地的 Herdr 按键绑定。即使远程服务器的配置不同,也能保持本地的肌肉记忆。编辑本地按键绑定后，可通过 UI 中的 `reload config` 应用更改，无需分离重连。想改用远程服务器配置时,使用 `--remote-keybindings server`。本地的自定义命令按键绑定不会被发送,因为那些命令会在远程主机上执行。
@@ -69,7 +71,7 @@ Host workbox
 herdr --remote workbox
 ```

-远程连接和已保存的 SSH 机器支持 Linux、macOS 和 Windows 客户端，目标可以是 x86_64 或 aarch64 的 Linux/macOS 主机，也可以是 x86_64 的 Windows 主机。只要两端支持稳定端点代数，版本就不必一致。Linux/macOS 上优先使用远程 `PATH` 中兼容的 `herdr`，再检查常见的直接安装、Homebrew、mise 和 Nix profile 路径。Windows 上检查 `PATH` 和当前有效的托管版本。如果没有兼容的二进制文件，交互式运行会询问是否安装或更新；非交互式运行直接失败，不修改主机。Linux/macOS 安装到 `~/.local/bin/herdr`，Windows 安装包含应用本地 ConPTY 运行时的完整软件包。如果 `~/.local/bin` 不在远程 `PATH` 中，Herdr 会发出警告。
+远程连接和已保存的 SSH 机器支持 Linux、macOS 和 Windows 客户端，目标可以是 x86_64 或 aarch64 的 Linux/macOS 主机，也可以是 x86_64 的 Windows 主机。Windows ARM64 主机通过 Windows 的 x64 模拟运行 x64 构建，仅提供尽力而为的支持，可能存在错误和其他问题。当主机报告 ARM64 时，显式远程连接和已保存机器的设置过程会显示模拟运行提示。只要两端支持稳定端点代数，版本就不必一致。Linux/macOS 上优先使用远程 `PATH` 中兼容的 `herdr`，再检查常见的直接安装、Homebrew、mise 和 Nix profile 路径。Windows 上检查 `PATH` 和当前有效的托管版本。如果没有兼容的二进制文件，交互式运行会询问是否安装或更新；非交互式运行直接失败，不修改主机。Linux/macOS 安装到 `~/.local/bin/herdr`，Windows 安装包含应用本地 ConPTY 运行时的完整软件包。如果 `~/.local/bin` 不在远程 `PATH` 中，Herdr 会发出警告。

 默认情况下,`herdr --remote` 通过一个临时 SSH 配置运行远程设置和桥接: 先包含你的 SSH 配置,再补充兜底的保活设置。已有的用户保活设置优先。Linux 和 macOS 客户端还会添加一个私有的单次连接 control socket 来复用连接;Windows OpenSSH 不使用此方式。设置 `[remote].manage_ssh_config = false` 可以不用 Herdr 生成的配置或 control socket,而使用普通 `ssh`。

@@ -312,6 +312,8 @@ description = "apply layout"
 `link_handler_id`;shell 插件也可以读取 `HERDR_PLUGIN_CLICKED_URL` 和
 `HERDR_PLUGIN_LINK_HANDLER_ID`。每个插件内的处理器按清单顺序检查。

+只有启用 `ui.mouse_capture` 时，点击链接才会调用插件。匹配的处理器先执行，启动失败会显示错误并停止。没有匹配处理器时，只有 HTTP(S) 链接会在外部打开。关闭捕获后，外层终端使用自己的快捷键和警告处理显式超链接。Windows Terminal URL 检测的注意事项见[鼠标操作](/zh-cn/docs/quick-start/#使用鼠标)。
+
 ## 存储

 v1 没有 Herdr 管理的插件存储 API。需要持久状态的插件应自己管理文件或
@@ -19,7 +19,13 @@ Herdr 会启动或连接到你的默认后台会话。你不需要管理 socket

 Herdr 是鼠标原生的,所以从点击开始。点击窗格、标签页、工作区和智能体来聚焦它们。拖动分割边框来调整大小。右键打开上下文菜单,包括分割窗格和创建标签页。拖选文本即可复制到剪贴板。双击一个词可以选中它；按住第二次点击并拖动，会按整词扩展选择。两种操作都会在松开鼠标时复制。复制不需要 Ctrl+C。

-当终端把带修饰键的点击传给 Herdr 时,Ctrl+点击可以打开窗格内的链接。这适用于 OSC 8 超链接及 `http://` 或 `https://` URL，包括首尾部分位于可见区域之外的换行链接。按住 Ctrl 并将指针移到链接上，会为可见部分添加下划线。移开指针、窗格内容变化或收到 Ctrl 释放事件时，高亮会清除；部分终端只在鼠标移动时报告修饰键变化。在 macOS 上,鼠标捕获开启时,请用 Ctrl+点击来触发 Herdr 处理的窗格链接;Cmd+点击只能通过终端原生的绕过路径使用,比如 Shift+Cmd+点击或 `ui.mouse_capture = false`。
+当终端把带修饰键的点击传给 Herdr 时,Ctrl+点击可以打开窗格内的链接。这适用于 OSC 8 超链接及 `http://` 或 `https://` URL，包括首尾部分位于可见区域之外的换行链接。按住 Ctrl 并将指针移到链接上，会为可见部分添加下划线。移开指针、窗格内容变化或收到 Ctrl 释放事件时，高亮会清除；部分终端只在鼠标移动时报告修饰键变化。
+
+`ui.mouse_capture = true`（默认）时，Herdr 处理 Ctrl+点击。匹配的已启用插件先执行。处理器启动失败会显示错误并停止。没有匹配插件的 `http://` 和 `https://` 链接在运行 Herdr 客户端的机器上用默认浏览器打开。其他链接需要匹配的插件。此模式不会把显式超链接传给外层终端，因此标签链接无法通过终端原生操作打开，包括 macOS 的 Command+点击。
+
+`ui.mouse_capture = false` 时，显式超链接会传给外层终端，使用终端通常的快捷键和警告。这些点击不会调用 Herdr 插件。关闭捕获也会禁用 Herdr 的鼠标操作，包括点击标签页和拖动分割边框。
+
+Windows Terminal 仍可能抢先打开从可见文本中检测到的 URL。要让插件可靠地优先处理这些 URL，请在 Windows Terminal 的 `settings.json` 中设置 `"experimental.detectURLs": false`。此设置适用于所有配置文件。Herdr 不会更改它。

 如果配置了 `ui.right_click_passthrough_modifier`,该修饰键加右键会把右键点击、按住和拖动手势发送给启用鼠标上报的窗格应用。

@@ -119,6 +119,8 @@ CLI 的 `herdr api snapshot` 会把当前 `session.snapshot` 响应输出为 JSO

 `pane.send_keys` 和 `pane.send_input.keys` 接受 Herdr 组合键字符串: 普通可打印键、`enter` 和 `esc` 这类特殊键、`ctrl+h`、`control+j`、`alt+x`、`shift+tab` 这类修饰组合键、`f1` 这类功能键,以及 `minus` 和 `plus` 这类命名标点。它们不接受 `prefix+` 绑定字符串。

+在 macOS 上,`pane.send_input`（由 `pane run` 使用）和 `agent.start` 会在命令进入输入队列前,检查终端当前规范模式的输入长度限制。编码后的行（包括 Enter）超限时,整条输入会被拒绝;请等待 shell 提示符出现后重试。多条短行和原始模式输入仍受支持。成功响应仍只表示已接受入队,不表示命令已执行。检查仅覆盖本次提交:它无法检查此前尚未完成的输入行,也无法保证排队期间终端模式不会改变。
+
 ```json
 {"id":"req_current","method":"pane.current","params":{"caller_pane_id":"w1:p1"}}
 {"id":"req_layout","method":"pane.layout","params":{"pane_id":"w1:p1"}}
@@ -16,6 +16,12 @@
      "id": "server",
      "title": "Server",
      "keys": [
+        {
+          "key": "server.allow_unelevated_clients",
+          "type": "boolean",
+          "default": "false",
+          "description": "Windows only: allow ordinary clients from the same account to control an elevated server and its administrator panes. Applies at server startup and requires a restart; config reload does not change access. The --allow-unelevated-clients startup flag enables sharing even when this setting is false."
+        },
        {
          "key": "server.headless_cols",
          "type": "integer",
@@ -0,0 +1,114 @@
+---
+title: Add Herdr support to your agent
+description: Report your coding agent's state and resume command to Herdr from your own code, without adding native support to Herdr.
+---
+
+If you build a coding agent, you can make it a first-class citizen in Herdr from your own code. You don't need a pull request to Herdr, and you don't need to wait for a Herdr release.
+
+Once your agent reports to Herdr, users get:
+
+- your agent's name and `idle`, `working`, or `blocked` state in the sidebar and in `herdr agent list`
+- notifications when it finishes or needs a decision
+- `herdr agent wait` and other automation that waits on agent state
+- the same session back in the same pane after a Herdr server restart
+
+Herdr owns the integrations for agents whose vendors don't ship one. If you maintain your agent, owning the integration yourself means you can fix it on your own release schedule.
+
+## How it works
+
+Every process in a Herdr pane inherits these environment variables:
+
+| Variable | Meaning |
+| --- | --- |
+| `HERDR_ENV` | `1` inside Herdr |
+| `HERDR_PANE_ID` | The pane your agent runs in |
+| `HERDR_BIN_PATH` | The Herdr binary that owns this pane |
+| `HERDR_SOCKET_PATH` | Herdr's API socket |
+
+Your agent makes three kinds of reports through `"$HERDR_BIN_PATH"`:
+
+1. **State.** Report `idle`, `working`, or `blocked` whenever it changes.
+2. **Resume command.** Report the command that reopens the current session.
+3. **Release.** Release the pane when your agent exits.
+
+Only report when `HERDR_ENV=1` and the other variables are set. Outside Herdr, your integration should do nothing.
+
+## Report state
+
+```bash
+"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
+  --source my-agent \
+  --agent my-agent \
+  --state working \
+  --seq 1
+```
+
+- Report `working` when a turn starts, `idle` when your agent is ready for input, and `blocked` when it needs the user to decide something. Add `--message` to explain a block.
+- `--agent` is the name users see. Use your own agent's name, not the name of an agent Herdr already supports.
+- `--source` identifies your integration. Keep it stable and unique. Don't start it with `herdr:`, because Herdr's own integrations use that prefix.
+- `--seq` is optional but recommended. It must increase with every report from your source, including across sessions and restarts of your agent. A timestamp works well. Herdr ignores reports whose number is not higher than the last one it accepted, so late or out-of-order reports can't overwrite newer state.
+
+To change how your agent appears without changing its state, such as a title or custom status text, see [Custom status labels](/docs/integrations/#custom-status-labels).
+
+## Report the resume command
+
+Put the command that resumes the current session after `--`. Include the options that session needs, such as the model or permission mode, so the resumed session behaves the same:
+
+```bash
+"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
+  --source my-agent \
+  --agent my-agent \
+  --state idle \
+  --seq 2 \
+  --agent-session-id "$SESSION_ID" \
+  -- my-agent --resume "$SESSION_ID" --model my-model
+```
+
+You can attach the command to any state report, or send it with `pane report-agent-session` when only the session changes. Report it again whenever your agent switches sessions.
+
+After a Herdr server restart, Herdr opens the pane in the same directory and runs that command there. The command must follow these rules:
+
+- The first word is a plain command name on the user's `PATH`, such as `my-agent`, not a path.
+- No argument contains an apostrophe or a control character.
+- At most 64 arguments and 8 KiB in total.
+- Your source must hold the pane first, so send a state report with `report-agent` before or along with the command. Otherwise Herdr answers with `resume_not_accepted`.
+
+Herdr rejects a command that breaks the first three rules with `invalid_resume_argv` and does not apply that report. Users can turn off resume with `[session] resume_agents_on_restore = false`.
+
+## Release on exit
+
+```bash
+"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \
+  --source my-agent \
+  --agent my-agent \
+  --seq 3
+```
+
+Releasing clears your agent's name, state, and resume command from the pane right away. Only release when the user actually quits. If your agent replaces one session with another in the same process, report the new session instead of releasing.
+
+If your agent exits without releasing, Herdr notices once the pane is back at its idle shell prompt and clears the agent and its resume command. This usually takes a second or two. It is a safety net, not a replacement for releasing.
+
+## Keep it out of the way
+
+- Don't let Herdr slow your agent down. Send reports in the background or with a short timeout, and ignore failures.
+- Send only the latest state. If several changes queue up while a report is in flight, drop the older ones.
+- Resume commands need Herdr 0.9.2 or later. Older versions ignore them, so state reports and release keep working there.
+
+## Use the socket directly
+
+`HERDR_BIN_PATH` and the CLI are the portable choice, including on Windows. If your agent needs direct IPC, send the equivalent `pane.report_agent`, `pane.report_agent_session`, and `pane.release_agent` requests described in the [Socket API](/docs/socket-api/#agent-state-reporting). The resume command goes in the `resume_argv` array.
+
+## Check your integration
+
+Start your agent in a Herdr pane, then check what Herdr sees:
+
+```bash
+herdr pane get "$HERDR_PANE_ID"
+herdr agent list
+```
+
+To test restore without touching your normal session, use a separate named session:
+
+1. Start `herdr --session my-agent-test`, then run your agent in a pane.
+2. Stop that session with `herdr session stop my-agent-test`.
+3. Start `herdr --session my-agent-test` again. The pane should run your resume command and your agent should report again.
@@ -0,0 +1,127 @@
+---
+title: Agent automation
+description: Use Herdr's layout, pane, and agent primitives to coordinate coding agents from scripts or other agents.
+---
+
+Use Herdr as an automation layer for coding agents. A script can control them, or one agent can create work for other agents, inspect their state, and collect their results. Choose the primitive that matches the job.
+
+## Three primitives
+
+| Primitive | Responsibility |
+| --- | --- |
+| Layout (`workspace`, `tab`, and pane topology) | Create and organize terminal locations. |
+| Pane | Control a raw terminal: run commands, send input, read output, and wait for output. |
+| Agent | Control a recognized coding agent by name or pane and lifecycle state. |
+
+A pane exists whether or not it contains an agent. An agent is the recognized process currently running inside a pane. `agent start` therefore requires an existing shell pane and never creates, splits, or moves layout.
+
+Creating a workspace also creates its first tab and root pane; creating a tab creates its root pane. Use the returned pane ID for the first process, and split only when that layout needs another terminal.
+
+Creation commands print JSON. Capture IDs from the response instead of predicting them:
+
+```bash
+created=$(herdr workspace create --cwd ~/project --label api --no-focus)
+pane_id=$(printf '%s\n' "$created" | jq -r '.result.root_pane.pane_id')
+
+split=$(herdr pane split "$pane_id" --direction right --no-focus)
+review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
+```
+
+`workspace create` returns `.result.workspace`, `.result.tab`, and `.result.root_pane`. `tab create` returns `.result.tab` and `.result.root_pane`. `pane split` returns the new pane as `.result.pane`.
+
+Moving a pane to another workspace changes its workspace-qualified pane ID. After any `pane move`, continue with `.result.move_result.pane.pane_id`; the response keeps the old value at `.result.move_result.previous_pane_id`. A running process keeps its launch-time Herdr environment, but the old `HERDR_PANE_ID` remains an alias for that terminal, so `--current` stays safe. New commands can still resolve the agent by name after the move, but a wait already in progress ends with `agent_not_running`.
+
+Use pane commands for shells, tests, servers, CI watchers, and other ordinary terminal processes. Use agent commands when Herdr needs to understand which agent is running or whether it is `working`, `blocked`, `done`, `idle`, or `unknown`.
+
+## Agent identity and launch
+
+A pane ID such as `w1:p2` identifies the terminal location. An agent name such as `reviewer` is a convenient alias for the current agent in that pane. Names must match `[a-z][a-z0-9_-]{0,31}` and be unique among live agents. The alias is cleared when that agent exits, is released, or is replaced; it does not permanently rename the pane.
+
+Agent commands accept either a unique live name or the pane ID that currently hosts the agent.
+
+An available shell pane is at its interactive shell prompt: the shell itself owns the foreground, with no foreground command, editor, or agent running. Return the pane to its prompt before calling `agent start`.
+
+`--kind` selects a supported agent and its canonical executable. Supported kinds are `pi`, `claude`, `codex`, `gemini`, `cursor`, `devin`, `agy`, `cline`, `omp`, `mastracode`, `opencode`, `copilot`, `kimi`, `kiro`, `droid`, `amp`, `grok`, `hermes`, `kilo`, `qodercli`, `qwen`, `letta`, `maki`, and `muse`. Arguments after `--` are passed unchanged to that executable.
+
+Successful `agent start` returns only after Herdr detects the expected agent in the same terminal and marks it ready for interactive input. If detection reports `blocked` during startup, the command returns `agent_not_ready` immediately. The name remains available for `agent read` and `agent send-keys`, and becomes ready for prompts after detection reports `idle`. Startup waits for 30 seconds by default; `--timeout` must be greater than 3000 and no more than 300000 milliseconds.
+
+```bash
+herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
+```
+
+Agents launched manually are detected automatically and can be addressed by pane ID. Give one a name when a stable human-readable target is useful:
+
+```bash
+herdr agent get w1:p2
+herdr agent rename w1:p2 reviewer
+```
+
+## Choose the control surface
+
+| Goal | Command |
+| --- | --- |
+| Run a shell command and submit it | `pane run` |
+| Send literal text without Enter | `pane send-text` |
+| Send terminal keys or modifier chords | `pane send-keys` |
+| Wait for text or a regular expression | `pane wait-output` |
+| Start a supported agent in an existing pane | `agent start` |
+| Submit a prompt, optionally waiting for it | `agent prompt` |
+| Send keys to an agent's interactive UI | `agent send-keys` |
+| Wait for agent lifecycle state | `agent wait` |
+
+`agent prompt` submits text plus encoded Enter and honors the terminal's live bracketed-paste mode. It can prompt an agent that is already working. If the agent is already `blocked`, it returns `agent_blocked` without sending terminal input; inspect the dialog and use `agent send-keys` for a deliberate response. Use `agent send-keys` for interactions such as `esc`, `up`, `enter`, or `ctrl+c`; `escape` is accepted as an alias for `esc`. Use the pane input commands when you deliberately want raw terminal control.
+
+Pane input addresses the terminal regardless of its current occupant. Agent input resolves the live agent and rejects the operation if that agent no longer controls the pane.
+
+`agent prompt --wait` rejects an agent already `blocked` with `agent_blocked`, without sending input or starting a wait. Otherwise, it writes the prompt and delayed Enter as one ordered submission before waiting. On Windows, Codex receives a paste boundary before Enter so submission does not depend on prompt size. The caller timeout includes submission time. If the prompt started from another non-working state, Herdr waits up to five seconds after submission to observe `working` or `blocked`. Otherwise, it returns `agent_prompt_stalled`; if the caller timeout expires first, it returns the normal `timeout` error. This prevents unrelated `idle`, `done`, or session changes from completing the wait. After Herdr observes activity, it waits for the requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. Standalone `agent wait` observes the current agent and returns immediately if its status already matches. Both commands default to `idle`, `done`, or `blocked`. Repeat `--until` to accept several exact states, for example `--until idle --until done`; use `--until unknown` explicitly when needed. On `agent prompt`, `--until` requires `--wait`.
+
+`idle` and `done` both mean the agent is ready for input. The CLI/API uses the server's seen state: `done` is idle but not yet marked seen, explicit `pane focus` / `agent focus` commands mark the target seen, and reads do not. Each TUI client tracks viewed completions independently, so a client's Done badge can differ from the CLI or another client's badge. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify its lifecycle confidently; it does not prove successful completion. Use exact `--until` states when that distinction matters.
+
+Startup readiness, restoring an idle conversation, and switching agent conversations do not count as completed work. An agent that starts working immediately can finish its first task without Herdr first seeing an idle prompt. Agent responses may include `completion_seq`, identifying the current idle transition as completed work independently of who has viewed it. It matches that transition's `state_change_seq`; startup and session changes do not set it. Older servers may omit this field. Clients connected to older servers use observed working states to guard Done badges, so they may miss a turn that starts and finishes between updates.
+
+A timeout or `agent_prompt_stalled` does not prove that no input was sent. Read the agent before retrying to avoid submitting the same prompt twice. IDs and agent names are scoped to one server; selecting another machine in the TUI does not retarget CLI commands running in an existing pane.
+
+`pane wait-output` does not interpret agent lifecycle. It polls the selected terminal snapshot and searches it immediately, so text that was already present can match. The default source name is `recent`; matching treats that source as unwrapped recent output from the latest 80 rendered terminal rows. `--lines` changes that row limit, and `--regex` uses Rust regular-expression syntax and matches one line at a time.
+
+At the CLI, both `pane read` and `agent read` print terminal text directly. The default is UTF-8 text with ANSI escapes stripped; use `--format ansi` or `--ansi` to preserve terminal escapes where the source exposes them. The `detection` source is always plain text. For recent sources, `--lines N` selects the last N rendered terminal rows before optional unwrapping; without it, reads default to 80 rows. For `visible` and `detection`, omitting `--lines` returns the full snapshot, while specifying it keeps the last N newline-delimited lines. The socket API returns the text at `.result.read.text`.
+
+## Alternate-screen history reads
+
+Full-screen agents such as Claude Code and OpenCode render transcript history in the terminal's alternate screen instead of Herdr's host scrollback. For an idle, recognized agent at the bottom of its transcript, text reads from `recent` or `recent-unwrapped` automatically use the agent's mouse-scroll interface when `--lines` requests more than the visible screen. Herdr collects overlapping pages and returns the viewport to the bottom before completing the read. The same behavior applies to `pane read` when the pane contains that agent; it requires no additional option.
+
+Other reads remain passive. Herdr does not move the application viewport for `visible`, `detection`, or ANSI reads, output waits and subscriptions, a manually scrolled agent, a direct attachment, or an application that does not report mouse-wheel input. An explicit `agent read --lines N` that needs alternate-screen history returns `agent_not_idle` while the agent is working, blocked, or unknown; wait for idle and retry, or use `--source visible`. Other recent reads return the available screen and host scrollback as before.
+
+If a full response is still unavailable, ask the agent to write it as Markdown in a temporary directory and reply only with the file path, then read the file directly.
+
+Successful `agent start`, `agent prompt`, and `agent wait` commands return the current agent at `.result.agent`. `pane wait-output` returns `.result.pane_id`, `.result.matched_line`, and the matched snapshot at `.result.read`.
+
+Wait commands have no default timeout and can wait indefinitely. On timeout or another server error, CLI commands print a JSON error to stderr and exit with status 1; invalid CLI syntax exits with status 2.
+
+## Recipes
+
+Start a helper, give it work, and wait for that work to settle:
+
+```bash
+split=$(herdr pane split --current --direction right --no-focus)
+review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
+herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
+herdr agent prompt reviewer "Review the current diff" --wait --timeout 120000
+herdr agent read reviewer --source recent-unwrapped --lines 120
+```
+
+Wait for an agent to ask for input, inspect it, and interact with its UI:
+
+```bash
+herdr agent wait reviewer --until blocked --timeout 120000
+herdr agent read reviewer --source recent-unwrapped --lines 80
+herdr agent send-keys reviewer esc
+```
+
+Run an ordinary process and wait for its output without treating it as an agent:
+
+```bash
+herdr pane run w1:p3 "just test --watch"
+herdr pane wait-output w1:p3 --regex "passed|failed" --timeout 120000
+```
+
+See the [CLI reference](/docs/cli-reference/) for the complete command and option list. Shell completions expose the same command tree interactively.
@@ -0,0 +1,67 @@
+---
+title: Agent skill file
+description: Install Herdr instructions for Claude Code or another coding agent.
+---
+
+Herdr ships a reusable agent skill file at [`skills/herdr/SKILL.md`](https://github.com/herdrdev/herdr/blob/master/skills/herdr/SKILL.md).
+
+Install that file into any coding agent that supports reusable skills or custom instructions. The skill teaches the agent how to control Herdr from inside a Herdr pane.
+
+Herdr also serves a separate guide at [`herdr.dev/agent-guide.md`](https://herdr.dev/agent-guide.md) for a different job: an agent helping a human learn, set up, or troubleshoot Herdr. The skill is for an agent operating Herdr; the guide is for an agent teaching a human.
+
+## What the skill does
+
+The skill tells an agent to use the `herdr` CLI when `HERDR_ENV=1` is set. That means the agent is running inside a Herdr-managed pane and can safely talk to the local Herdr socket.
+
+With the skill installed, an agent can:
+
+- inspect workspaces, tabs, panes, and neighboring agents
+- split panes and run commands without stealing focus
+- read pane output and recent logs
+- wait for servers, tests, or another agent to finish
+- start helper agents in sibling panes
+
+The skill is a Markdown instruction file for agents. If Herdr is already installed, run `herdr --skill` to print the release-matched copy bundled with that binary.
+
+## Install it
+
+Install the skill with `npx skills`:
+
+```bash
+npx skills add herdrdev/herdr --skill herdr -g
+```
+
+If you installed the skill while it lived at the repository root, rerun this add command once instead of using `skills update`. The add command replaces the oversized copy and records the new location.
+
+The `-g` flag installs it globally for supported agents. Omit `-g` to install it into the current project.
+
+Use the repository copy as the manual fallback and source of truth:
+
+```text
+https://github.com/herdrdev/herdr/blob/master/skills/herdr/SKILL.md
+```
+
+For agents with a skill system, install that file as a skill named `herdr`. For agents without a skill system, paste the file into the agent's project or user instructions.
+
+After installation, start the agent inside Herdr:
+
+```bash
+herdr
+claude
+```
+
+Or use any other coding agent in a Herdr pane so `HERDR_ENV=1` is available to the agent process.
+
+## Safety rule
+
+The skill starts with one guardrail: if `HERDR_ENV=1` is not set, the agent should stop and say it is not running inside a Herdr-managed pane.
+
+This prevents an agent outside Herdr from trying to control a session it does not own.
+
+## Agent-facing reference
+
+The full command guide lives in the skill file itself. It covers pane IDs, `pane split`, `pane run`, `pane read`, `pane wait-output`, `agent wait`, workspace and tab commands, and coordination recipes.
+
+Read the source file here:
+
+[Open `SKILL.md` on GitHub →](https://github.com/herdrdev/herdr/blob/master/skills/herdr/SKILL.md)
@@ -0,0 +1,175 @@
+---
+title: Agents
+description: See which coding agents work with Herdr, either supported by Herdr or supporting Herdr themselves, and how agent state works.
+---
+
+Herdr is built for running more than one coding agent at a time. Each agent stays in a real terminal pane with its shell, logs, prompts, and running processes intact. Herdr tracks which panes contain agents, rolls their state up to tabs and workspaces, and lets you jump straight to the pane that needs attention instead of polling every terminal by hand.
+
+To coordinate agents from scripts or from another agent, see [Agent automation](/docs/agent-automation/).
+
+## Supported agents
+
+Agents get Herdr support in one of two ways: Herdr supports them, or they support Herdr themselves. Either way you see each agent's `idle`, `working`, and `blocked` state, get notified when it finishes or needs you, and can wait on it from scripts.
+
+Other agents still run normally in Herdr panes. They just show up as plain terminals.
+
+### Supported by Herdr
+
+Herdr recognizes these agents and reads their state from what they draw on screen. To get the same session back after a Herdr server restart, install the agent's integration with `herdr integration install <name>`. See [Integrations](/docs/integrations/) for what each one installs.
+
+| Agent | Integration | Notes |
+| --- | --- | --- |
+| Claude Code | `claude` | |
+| Codex | `codex` | |
+| GitHub Copilot CLI | `copilot` | |
+| Cursor Agent CLI | `cursor` | |
+| OpenCode | `opencode` | also reports state |
+| Pi | `pi` | also reports state |
+| OMP | `omp` | state requires the integration |
+| Droid | `droid` | |
+| Devin CLI | `devin` | |
+| Kimi Code CLI | `kimi` | also reports state |
+| Kilo Code CLI | `kilo` | also reports state |
+| Hermes Agent | `hermes` | |
+| Qoder CLI | `qodercli` | |
+| Qwen Code | `qwen` | |
+| Letta Code | `letta` | CLI install only |
+| MastraCode | `mastracode` | state requires the integration |
+| Grok CLI | `grok` | |
+| Antigravity CLI | `antigravity-cli` | |
+| Amp | none | state only |
+| Kiro CLI | none | state only |
+| Maki | none | state only |
+| Gemini CLI | none | state only, less tested |
+| Cline | none | state only, less tested |
+
+### Supported by the agent
+
+These agents report their own state to Herdr. There is nothing to install; run them in a Herdr pane.
+
+<ul class="agent-logos">
+  <li><a href="https://commandcode.ai"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/command-code.svg')" }} aria-hidden="true"></span>Command Code</a></li>
+  <li><a href="https://github.com/charmbracelet/crush"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/crush.svg')" }} aria-hidden="true"></span>Crush</a></li>
+  <li><a href="https://kiro.dev/cli/"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/kiro-mask.svg')" }} aria-hidden="true"></span>Kiro CLI</a></li>
+  <li><a href="https://dev.meta.ai/products/muse-code"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/muse-code.svg')" }} aria-hidden="true"></span>Muse Code</a></li>
+  <li><a href="https://github.com/PrimeIntellect-ai/prime-agent"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/prime-agent.svg')" }} aria-hidden="true"></span>Prime Agent</a></li>
+</ul>
+
+An agent that also reports its resume command comes back in the same session after a Herdr server restart.
+
+If you build a coding agent, [Add Herdr support to your agent](/docs/add-herdr-support/) shows how to join this list. It takes a few calls to Herdr's CLI or socket, and no change to Herdr.
+
+## How status works
+
+For agents Herdr supports, Herdr finds the agent's process in each pane and reads the live bottom of the pane, not the part you scrolled to. Rules in a detection manifest decide whether that screen means `idle`, `working`, or `blocked`. When an integration also reports state, Herdr uses those reports instead of reading the screen.
+
+For agents that support Herdr, the agent's own reports decide the state.
+
+## VMs and sandbox wrappers
+
+On Linux and macOS, a host-visible wrapper can hide the real agent process from Herdr. Set `HERDR_AGENT=<agent>` on the wrapper command to tell Herdr which existing agent screen manifest to use. For example, run `HERDR_AGENT=claude fence -- claude` on Linux or `HERDR_AGENT=claude nono run --profile claude-code -- claude` on macOS. The hint applies only to that foreground process. Herdr cannot see it if you set it only inside a VM or container. Avoid exporting it globally unless every inherited foreground process should be treated as that agent.
+
+Some restricted Linux runtimes do not expose a terminal foreground process group. Start the Herdr server with `HERDR_PROCESS_DETECTION=child-groups` to opt into direct child-process-group inference when native detection is unavailable. Native detection remains preferred, and the default `native` mode never performs this inference. The opt-in mode is best effort: a newer background job can be mistaken for the foreground job. The variable is read by the server and requires a restart; set it in the remote server environment rather than on an attaching client.
+
+## Blocked state
+
+Blocked detection is deliberately strict for screen-manifest agents. Herdr only marks `blocked` when the live bottom-buffer snapshot matches known visible approval, question, or permission UI. If no manifest rule matches for a known agent, Herdr falls back to `idle` and labels that fallback as `default_known_agent_idle_fallback` in explain output.
+
+Unusual new agent prompts may initially show as `idle` instead of `blocked` until Herdr learns that screen shape. Detection itself does not send input, but automation that trusts a mistaken idle state can type into an approval dialog. Inspect unexpected prompts before sending more input; idle status is not authorization to approve an action.
+
+Antigravity and Grok count as idle once they return to their prompt, even if background tasks, monitors, or subagents are still running. `agent wait` and `agent prompt --wait` observe the agent's state, not completion of those jobs.
+
+Suspending an agent with Ctrl+Z preserves its name, session reference, and hook authority while the exact process remains alive behind the shell or another non-agent command. Returning with `fg` keeps that identity. This does not cover another recognized agent taking over the foreground. A retained identity does not mean the agent can receive input while suspended; inspect the pane before prompting it.
+
+## Detection manifests
+
+Bundled manifests live inside Herdr. Herdr also checks herdr.dev for remote manifest updates and applies valid per-agent rule updates automatically without requiring a Herdr restart. Remote manifests are stored in Herdr's state directory. Set `[update] manifest_check = false` to disable background remote manifest checks.
+
+Local overrides can replace a remote or bundled manifest from the platform config directory:
+
+```text
+~/.config/herdr/agent-detection/<agent>.toml
+```
+
+Local overrides always win. Without a local override, Herdr uses the newer compatible manifest between the cached remote manifest and the bundled manifest in the running binary. On debug builds, the same config helper may use a development directory such as `herdr-dev`. Invalid override files are ignored with a warning and Herdr falls back to the cached remote or bundled manifest for that agent.
+
+Remote manifests patch detection rules for agents Herdr already knows how to identify. Adding a completely new agent still requires a Herdr binary update for process detection, labels, and integration behavior.
+
+The running server loads active manifests into memory on startup. Automatic remote manifest updates reload that in-memory cache after new rules are written. Run `herdr server update-agent-manifests` to fetch remote manifest updates immediately and reload the running server. After editing a local override manually, restart Herdr or run `herdr server reload-agent-manifests` to apply the file to the running server.
+
+Use `herdr agent explain` when a pane shows the wrong state:
+
+```bash
+herdr agent explain <target>
+herdr agent explain --file screen.txt --agent codex --json
+```
+
+Live explain is evaluated by the running server, so it reflects the active manifest cache. The explain output shows the agent, final state, whether screen detection was skipped by a full lifecycle authority, manifest source and version, cached remote version, local override shadowing, remote update status, matched rule, visible evidence flags, matcher and region evidence for evaluated rules, skipped-update reason for transcript viewers, and the idle fallback reason when no rule matched.
+
+Herdr can run inside tmux as the outer terminal environment. Agent detection does not inspect tmux sessions launched inside a Herdr pane. If a shell framework auto-enters tmux inside Herdr, Herdr sees `tmux` as the pane process instead of the agent behind it.
+
+If your shell automatically attaches to tmux whenever `TMUX` is unset, update its startup rule to exclude Herdr panes. Reattaching the outer tmux session from inside a Herdr pane can recursively shrink the terminal and make it flicker. Add the `HERDR_ENV` check to your existing condition before it runs tmux:
+
+```zsh
+if [[ -z ${TMUX:-} && ${HERDR_ENV:-} != 1 ]]; then
+  tmux new-session -A -s my-session
+fi
+```
+
+## State rollups
+
+The sidebar rolls state upward.
+
+A blocked agent makes its pane, tab, and workspace look blocked. A working agent makes the workspace look active. A done agent stays visible until you view it.
+
+This is the main Herdr workflow: start several agents, let them work in parallel, and use the sidebar to see which project needs a decision, which one is still running, and which one is ready to review.
+
+## Custom agent labels
+
+You can rename an agent target for display:
+
+```bash
+herdr agent rename w1:p1 reviewer
+herdr agent rename reviewer --clear
+```
+
+Targets accept a unique live agent name or the pane ID that currently hosts the agent. Terminal IDs and bare agent-kind labels are not accepted.
+
+## Custom status labels
+
+Integrations report lifecycle state as semantic state only. Add display customization separately with pane metadata tokens.
+
+```bash
+herdr pane report-agent w1:p1 \
+  --source custom:indexer \
+  --agent docs-bot \
+  --state working
+
+herdr pane report-metadata w1:p1 \
+  --source custom:indexer-display \
+  --token summary=indexing
+```
+
+`state` controls waits, notifications, and rollups. The `summary` token is display-only and can be used as `$summary` in an Agent sidebar row.
+
+Agent sidebar rows can also opt into `terminal_title` or `terminal_title_stripped`; neither appears in the default rows. The first shows the latest safety-normalized OSC 0/2 terminal title. The second removes one recognized leading activity or spinner glyph and following whitespace. Herdr owns these values on the server; they are ephemeral across a cold restart and remain independent of metadata titles and semantic agent state. Spinner animation can therefore update the raw title without producing a pane update when the stripped text stays the same.
+
+## Attach directly to an agent
+
+Attach your current terminal to one agent terminal instead of the full Herdr UI:
+
+```bash
+herdr agent attach reviewer
+```
+
+Detach with `ctrl+b q`. Send a literal `ctrl+b` with `ctrl+b ctrl+b`.
+
+Scroll with the mouse wheel or plain page up/page down. Normal input jumps back to the bottom.
+
+Use `--takeover` if another direct attach client already owns input:
+
+```bash
+herdr agent attach reviewer --takeover
+```
+
+Use `herdr terminal attach <terminal_id>` when you want the same direct attach behavior for a non-agent terminal.
@@ -0,0 +1,574 @@
+---
+title: CLI reference
+description: Herdr commands for sessions, workspaces, tabs, panes, notifications, agents, waits, integrations, and status.
+---
+
+Herdr’s CLI talks to the running server over the same local socket API used by integrations and agents.
+
+Most commands print JSON responses for deterministic automation in scripts.
+
+## Launch and status
+
+```bash
+herdr                         # launch or attach to the default session
+herdr --remote workbox        # attach through SSH, using local keybindings
+herdr --default-config        # print default config
+herdr update                  # download and install from the configured channel
+herdr completion zsh          # generate a zsh completion script
+herdr channel show            # print stable or preview
+herdr channel set preview     # opt into preview builds
+herdr channel set stable      # return a direct install to stable
+herdr --version               # print version
+```
+
+Optional launch and update settings:
+
+- Add `--session <name>` to use a named session instead of the default.
+- Add `--remote-keybindings server` to remote attach to use server keybindings instead of local ones.
+- Experimental live handoff requires explicit `--handoff` on `herdr --remote` or `herdr update`. It is not the normal setup or connection path; see [Updates](/docs/install/#update).
+
+Status commands:
+
+```bash
+herdr status
+herdr status server
+herdr status client
+```
+
+API schema commands:
+
+```bash
+herdr api schema
+herdr api schema --json
+herdr api schema --output herdr-api.schema.json
+```
+
+`herdr api schema` prints a short summary of the socket protocol schema bundled
+with the installed binary. Use `--json` for the full JSON Schema document, or
+`--output PATH` to write that document to a file.
+
+## Saved SSH machines
+
+```bash
+herdr machine list
+herdr machine add workbox
+herdr machine add workbox --label "Build machine"
+herdr machine rename <profile-id> --label "New name"
+herdr machine disable <profile-id>
+herdr machine enable <profile-id>
+herdr machine remove <profile-id>
+```
+
+In an interactive terminal, `machine add` discovers running sessions and lets you choose when several are running. No running sessions, or no Herdr installation, uses `default`; failed queries against an installed binary require an explicit choice. Add `--remote-session <name>` to skip discovery. Non-interactive commands use `default` unless that flag is supplied. `machine list` accepts optional `--json` for scripts. See [Connecting machines](/docs/connecting-machines/) for the full setup and connection guide.
+
+`machine add` checks the remote installation's capabilities, installs or updates with approval only when needed, and starts the requested session's background server before saving. Compatible release versions do not need to match. Run setup in an interactive terminal when installation or restart approval is required; failed or cancelled setup does not save a profile. Replacing a running server requires explicit approval with a default answer of No, and stops its pane processes. `machine add` never enables experimental handoff implicitly.
+
+Changes apply automatically to open local Herdr clients, normally within a second. Added or enabled machines connect in the background; renaming does not reconnect. Removing or disabling disconnects only that machine and leaves its remote sessions running. Removing the machine you are viewing returns to Local, or shows Local as unavailable until it reconnects. Each profile stores an opaque ID, label, SSH target, explicit remote session, and enabled state in client state. Herdr does not store passwords, private keys, or other SSH credentials.
+
+Use `herdr machine status [<label-or-id>] [--json]` for fresh, noninteractive SSH and remote Herdr checks. `reachable` describes this check, not a TUI's current connection. Use `herdr machine reconnect <label-or-id>` in a terminal for SSH authentication and verification; it does not install or update Herdr. Open clients retry failed connections within 30 seconds. Clicking `! auth` or `! error` shows the latest error and CLI guidance; collapsed sidebars show `!`. See [Recovering SSH authentication](/docs/connecting-machines/#recovering-ssh-authentication) for platform limits. For remote setup, use `herdr --remote workbox`, adding `--session <name>` only for a named session.
+
+Workspace, tab, pane IDs, and agent names belong to a single server. Selecting a machine in the UI does not retarget CLI commands. Use the global **prefix** `--machine <label-or-id>` to route API commands to a saved SSH machine:
+
+```bash
+herdr --machine "Build machine" agent list
+herdr --machine <profile-id> pane list
+herdr --machine "Build machine" agent prompt w1:p1 "review this change"
+herdr --machine "Build machine" worktree create --cwd /srv/project --branch review
+```
+
+The selector must match an enabled saved profile ID or a unique, case-sensitive label, not an arbitrary SSH hostname. The saved remote session is used; combining `--machine` with `--session` or `--remote` is an error. Without the prefix, commands retain their existing local session/socket behavior.
+
+Supported commands are `workspace`, `worktree`, `tab`, `pane`, `notification`, `agent` (except `attach` and local `explain --file`), `api snapshot`, `status server`, and API-backed plugin commands (`link`, `unlink`, `enable`, `disable`, `list`, `action`, `log`, `pane`). Server commands support `stop`, `reload-config`, `agent-manifests`, and `reload-agent-manifests`. Local installation/configuration commands, plugin installation, session management, and interactive terminal attachment are not forwarded.
+
+Requests and responses travel through the JSON API over non-interactive SSH; API payloads are not interpolated into the SSH shell command. No open TUI is required, and the bridge never installs, starts, or restarts a server. Update the local CLI and remote Herdr installation to support machine forwarding, and keep the running remote server's API protocol compatible. Authentication, unavailable machines, and incompatible versions fail without falling back to Local. Requests are not automatically retried after connection failure.
+
+Local pane IDs are not inherited by remote commands. Use explicit remote IDs; `--current` cannot refer to the caller's local pane. Remote worktree paths must be absolute, `~`, or start with `~/` (expanded on the server); plugin link paths must be absolute. The prefix targets one machine at a time; combined listings and routing through another TUI's connections are not included.
+
+## Shell completions
+
+```bash
+herdr completion zsh
+herdr completions zsh
+herdr completion bash
+herdr completion fish
+herdr completion powershell
+herdr completion elvish
+```
+
+`completion` prints the script to stdout. `completions` is an alias. For a
+temporary zsh session, load the script directly:
+
+```bash
+source <(herdr completion zsh)
+```
+
+For a persistent zsh setup, write the generated `_herdr` function somewhere on
+your `fpath` before `compinit` runs:
+
+```bash
+mkdir -p ~/.zfunc
+herdr completion zsh > ~/.zfunc/_herdr
+```
+
+Then make sure your `.zshrc` contains:
+
+```zsh
+fpath=(~/.zfunc $fpath)
+autoload -Uz compinit
+compinit
+```
+
+## Server
+
+```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` runs the headless server explicitly. Use it for supervised or service-style setups. `reload-config` applies reloadable settings without restarting panes. `agent-manifests` shows the active agent detection manifest sources, cached remote versions, and last remote update results. `update-agent-manifests` fetches remote manifest updates immediately, reloads them into the running server, and prints the updated manifest status; pass `--json` for the raw status response. `reload-agent-manifests` reloads agent detection manifests into the running server after local override edits.
+
+## Notifications
+
+```bash
+herdr notification show <title> [--body TEXT] [--position top-left|top-right|bottom-left|bottom-right] [--sound none|done|request]
+```
+
+`notification show` uses the configured `[ui.toast]` delivery. `--position` only affects in-app Herdr toasts. `--sound` defaults to `none`; `done` and `request` play the existing finished and needs-attention sounds only when the notification is shown.
+
+## Sessions
+
+```bash
+herdr session list [--json]
+herdr session attach <name>
+herdr session stop <name> [--json]
+herdr session delete <name> [--json]
+```
+
+Use `default` as the session name when you need to stop the default session explicitly.
+
+## Workspaces
+
+```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 report-metadata <workspace_id> --source ID [--token NAME=VALUE] [--clear-token NAME] [--seq N] [--ttl-ms N]
+herdr workspace close <workspace_id> [--group]
+```
+
+Create a workspace without stealing focus:
+
+```bash
+herdr workspace create --cwd ~/project --label api --no-focus
+```
+
+A workspace is a top-level project or work context. Creating one also creates its first tab and root pane. The JSON response exposes their IDs as `.result.workspace.workspace_id`, `.result.tab.tab_id`, and `.result.root_pane.pane_id`.
+
+## Worktrees
+
+```bash
+herdr worktree list [--workspace ID | --cwd PATH] [--trust-repository]
+herdr worktree create [--workspace ID | --cwd PATH] [--branch NAME] [--base REF] [--path PATH] [--label TEXT] [--focus] [--no-focus] [--trust-repository]
+herdr worktree open [--workspace ID | --cwd PATH] (--path PATH | --branch NAME) [--label TEXT] [--focus] [--no-focus] [--trust-repository]
+herdr worktree remove --workspace ID [--force] [--trust-repository]
+```
+
+Worktrees are normal Herdr workspaces with Git checkout provenance. `worktree create` creates a Git worktree checkout, opens it as a workspace, and groups it with the parent repo workspace. If `--branch` names an existing local branch, Herdr checks it out; otherwise it creates the branch from `--base` or `HEAD`. Without `--path`, Herdr creates the checkout under `<worktrees.directory>/<repo>/<branch-slug>`.
+
+`workspace close` closes only Herdr state. Closing a primary workspace while linked-worktree workspaces are open requires `--group`; without it, the command leaves the group open and returns `workspace_group_close_required`. To delete the checkout, run `worktree remove`. It runs `git worktree remove`, never deletes the branch, and requires `--force` when Git refuses a dirty checkout.
+
+Git rejects repositories owned by another user by default. If you have independently verified the repository, pass `--trust-repository` to trust its resolved path for that command only. Herdr does not change your Git configuration.
+
+## Tabs
+
+```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>
+```
+
+A tab is another terminal layout inside a workspace. Without `--workspace`, `tab create` uses the active workspace and fails if none exists. Its JSON response exposes `.result.tab.tab_id` and `.result.root_pane.pane_id`. Closing a workspace's last tab also closes the workspace, matching the TUI close-tab action. If `confirm_close` is enabled and closing the tab would also close a whole worktree group, `tab close` returns a `confirmation_required` error instead.
+
+With `ui.confirm_close` enabled, the TUI asks for confirmation before closing a workspace's last tab or its only pane from a keybinding or the tab/pane menu. Ordinary pane closes and CLI/API closes remain immediate.
+
+Workspace and tab creation, and pane splitting, leave focus unchanged by default. `--focus` selects the new layout; `--no-focus` states the default explicitly. Without `--cwd`, new terminals follow the configured `terminal.new_cwd` policy, which follows the source pane or workspace by default. Each `--env KEY=VALUE` adds or replaces that variable in the new root shell.
+
+## Panes
+
+```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 input [<pane_id>|--pane ID|--current] --right-click herdr|pane
+herdr pane split [<pane_id>|--pane ID|--current] --direction right|down [--ratio FLOAT] [--cwd PATH] [--env KEY=VALUE] [--right-click herdr|pane] [--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>
+```
+
+For pane commands that accept `--current`, Herdr uses the calling pane's
+`HERDR_PANE_ID` when the command runs inside a Herdr pane. For `pane split`,
+an explicit pane id or `--pane ID` splits that pane. An omitted target splits
+the calling pane when `HERDR_PANE_ID` is available, otherwise the focused pane.
+`--current` requires a calling pane and errors when `HERDR_PANE_ID` is unavailable.
+The split response exposes the new pane ID as `.result.pane.pane_id`.
+
+`pane input --right-click pane` forwards unmodified right-click gestures to a
+mouse-reporting pane application. `herdr` restores the default pane menu.
+Right-clicking the pane frame still opens Herdr's menu. `pane split
+--right-click pane` applies the same policy to the new pane at creation.
+
+After `pane move`, use `.result.move_result.pane.pane_id` for later commands. A cross-workspace move changes the workspace-qualified pane ID; the prior value remains at `.result.move_result.previous_pane_id`. The running process keeps its launch-time `HERDR_PANE_ID`, `HERDR_TAB_ID`, and `HERDR_WORKSPACE_ID`; Herdr retains the old pane ID as an alias for that terminal, so pane commands using `--current` still resolve it. A live agent name follows the terminal and continues to resolve after the move.
+
+Read output:
+
+```bash
+herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi] [--raw]
+herdr pane read <pane_id> --source visible --ansi
+herdr pane read <pane_id> --source recent-unwrapped --lines 120
+```
+
+`pane read` prints UTF-8 terminal text directly. ANSI escapes are stripped by default; use `--format ansi` or `--ansi` to preserve them where the source exposes styling. The `detection` source is always plain text. For recent sources, `--lines N` selects the last N rendered terminal rows before optional unwrapping; without it, reads default to 80 rows. For `visible` and `detection`, omitting `--lines` returns the full snapshot, while specifying it keeps the last N newline-delimited lines. `agent read` uses the same output and line behavior.
+
+Send input:
+
+```bash
+herdr pane send-text <pane_id> <text>
+herdr pane send-keys <pane_id> <key> [key ...]
+herdr pane run <pane_id> <command>
+```
+
+`<key>` uses Herdr key-combo syntax: plain printable keys such as `a`,
+special keys such as `enter`, `tab`, `esc`, `backspace`, `left`, `right`,
+`up`, and `down`, modifier chords such as `ctrl+h`, `control+j`, `alt+x`,
+and `shift+tab`, function keys such as `f1`, and named punctuation such as
+`minus`, `plus`, and `backtick`. Legacy `C-c` and `c-c` are accepted as
+aliases for `ctrl+c`.
+`esc` is the canonical spelling; `escape` is also accepted.
+
+`pane run` honors live bracketed-paste mode and submits text plus Enter atomically. Prefer it over `send-text` plus `send-keys Enter` for commands; the separate send operations remain low-level and non-submitting.
+
+Report agent state from custom hooks:
+
+```bash
+herdr pane report-agent <pane_id> \
+  --source ID \
+  --agent LABEL \
+  --state idle|working|blocked|unknown \
+  [--message TEXT] \
+  [--seq N] \
+  [--agent-session-id ID] \
+  [--agent-session-path PATH] \
+  [-- RESUME_COMMAND...]
+
+herdr pane report-agent-session <pane_id> \
+  --source ID \
+  --agent LABEL \
+  [--seq N] \
+  [--agent-session-id ID] \
+  [--agent-session-path PATH] \
+  [--session-start-source SOURCE] \
+  [-- RESUME_COMMAND...]
+
+herdr pane release-agent <pane_id> \
+  --source ID \
+  --agent LABEL \
+  [--seq N]
+```
+
+`report-agent-session` updates native session identity without reporting lifecycle state. `release-agent` ends that source's lifecycle authority when its agent process exits.
+
+Arguments after `--` are the command Herdr runs to resume this session after a server restart. The first argument must be a plain command name on `PATH`, and no argument may contain an apostrophe.
+
+`pane get`, `pane list`, `agent get`, and `agent list` include a read-only `agent_session` object when an official integration has reported a native session reference. If no native session reference is stored, the field is omitted.
+
+Those commands include `foreground_cwd` when Herdr can resolve the cwd of the foreground process controlling the pane. The `cwd` field remains the pane/workspace cwd used for labels and follow-cwd behavior.
+
+`pane get` and `pane list` include `scroll` when terminal scroll metrics are available. `scroll.offset_from_bottom == 0` means the pane is at the bottom of its scrollback.
+
+Report display-only pane metadata without taking over semantic state:
+
+```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] \
+  [--state-label STATUS=TEXT] \
+  [--clear-state-labels] \
+  [--token NAME=VALUE] \
+  [--clear-token NAME] \
+  [--seq N] \
+  [--ttl-ms N]
+```
+
+`STATUS` is one of `idle`, `working`, `blocked`, `done`, or `unknown`. `--agent` and `--applies-to-source` guard only `--title`, `--display-agent`, and `--state-label`. They do not guard token patches; token reporters own clearing or TTL refresh. Use `--display-agent` to change the visible name.
+
+Metadata text is normalized before storage. Herdr trims surrounding whitespace, removes control characters, and caps `--title`, `--display-agent`, each `--state-label`, and token values at 80 characters. Empty normalized token values clear that key.
+
+`--token` patches one named display value; `--clear-token` removes one. Unmentioned tokens remain unchanged. Pane tokens are available to Agent sidebar rows as `$name`; workspace tokens are available to Space rows. TTL applies independently to the token keys updated by that call.
+
+`--source` and `--applies-to-source` must be 80 characters or fewer and may contain only ASCII letters, digits, colon, dot, underscore, and hyphen. `--ttl-ms` makes metadata expire automatically and must be between `1` and `86400000` milliseconds. Omit it for metadata that should stay until replaced, cleared, or the pane closes. `--seq` lets Herdr ignore stale reports from the same `--source`; stale reports are accepted by the API but ignored by pane state. A pane or workspace accepts sequenced token reports from at most 32 distinct sources during its lifetime; clearing or expiry does not release those source slots.
+
+## Agents
+
+For the pane-versus-agent model and complete orchestration examples, see [Agent automation](/docs/agent-automation/).
+
+```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-keys <target> <key> [key ...]
+herdr agent prompt <target> <text> [--wait] [--until STATUS]... [--timeout MS]
+herdr agent rename <target> <name>|--clear
+herdr agent focus <target>
+herdr agent wait <target> [--until STATUS]... [--timeout MS]
+herdr agent attach <target> [--takeover]
+herdr agent start <name> --kind KIND --pane ID [--timeout MS] [-- <agent-args...>]
+herdr agent explain <target> [--json|--verbose]
+herdr agent explain --file PATH --agent LABEL [--json|--verbose]
+```
+
+Agent targets are either a unique live agent name or the pane ID that currently hosts the agent. Terminal IDs and bare agent-kind labels are not agent targets. Agents started through `agent start` require a name; manually launched agents remain unnamed and use their pane ID.
+
+`agent start` activates an existing available shell pane: the pane's interactive shell must own the foreground, with no foreground command, editor, or agent running. Topology must be created separately. Names are unique among live agents and must match `[a-z][a-z0-9_-]{0,31}`. The kind selects Herdr's canonical interactive executable, while arguments after `--` are passed to that executable. Supported kinds are `pi`, `claude`, `codex`, `gemini`, `cursor`, `devin`, `agy`, `cline`, `omp`, `mastracode`, `opencode`, `copilot`, `kimi`, `kiro`, `droid`, `amp`, `grok`, `hermes`, `kilo`, `qodercli`, `qwen`, `letta`, `maki`, and `muse`. A name follows the current pane occupant and is cleared when that agent exits, is released, or is replaced. Temporary detection uncertainty does not clear it.
+
+A successful start returns only after the expected agent owns the same terminal and is ready for interactive input. If detection reports `blocked` during startup, the command returns `agent_not_ready` immediately. The name remains available for `agent read` and `agent send-keys`, and becomes ready for prompts after detection reports `idle`. The default startup timeout is 30000 milliseconds; explicit values must be greater than 3000 and no more than 300000.
+
+`agent prompt` honors live bracketed-paste mode and writes text followed by delayed Enter as one ordered submission, including while the agent is working. Success without `--wait` acknowledges the writes, not the start of a turn. On Windows, Codex receives a paste boundary before Enter so submission does not depend on prompt size; the caller timeout includes submission time. If the agent is already `blocked`, it returns `agent_blocked` without sending input. With `--wait`, a prompt sent from another non-working state has up to five seconds after submission to produce an observed `working` or `blocked` state or Herdr returns `agent_prompt_stalled`; if the caller timeout expires first, Herdr returns the normal `timeout` error. This prevents unrelated `idle`, `done`, or session changes from completing the wait. After activity is observed, it waits for the first requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. `--until` narrows the matching states and is rejected unless `--wait` is also present. Standalone `agent wait` returns immediately when the current status matches. Both default to `idle`, `done`, or `blocked`; use `--until unknown` explicitly when needed.
+
+`idle` and `done` both mean ready for input. The CLI/API uses the server's seen state: `done` is idle but not yet marked seen, explicit `pane focus` / `agent focus` commands mark the target seen, and reads do not. Each TUI client tracks viewed completions independently, so its Done badge can differ from the CLI or another client. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify it confidently, not that its work succeeded.
+
+`agent send-keys` sends logical terminal keys such as `enter`, `up`, `esc`, or `ctrl+c`. Herdr validates every key before writing any bytes. `agent read` reads the resolved terminal stream, and `agent rename` names an already detected agent.
+
+`agent explain` asks the running server to classify the same bottom-buffer detection snapshot used by screen detection, so live output reflects the server's active manifest cache. Because this uses the `agent.explain` socket method, restart or hand off to an updated server after upgrading Herdr before using live explain. Use `--file PATH --agent LABEL` to explain a saved fixture locally instead. The default output shows the agent, final state, manifest source and version, matched rule with its region evidence, and any fallback, skip, or warning reasons. Add `--verbose` for visible evidence flags, cached remote version, local override shadowing, remote update status, and the full evaluated-rules list with matcher and region evidence. Add `--json` for issue reports or tests.
+
+Use `pane send-text`, `pane send-keys`, `pane run`, and `terminal attach` for ordinary terminals, servers, tests, shells, or low-level terminal control. Use `pane run` when you want to submit a command with Enter.
+
+## Direct terminal attach
+
+```bash
+herdr terminal attach <terminal_id> [--takeover]
+herdr terminal session control <target> [--takeover] [--cols N] [--rows N]
+herdr terminal session observe <target> [--cols N] [--rows N]
+herdr terminal title set <title>
+herdr terminal title clear
+```
+
+Detach from direct attach with `ctrl+b q`. Send literal `ctrl+b` with `ctrl+b ctrl+b`.
+`terminal session control` opens a writable live terminal stream for a pane,
+terminal, or agent target. It prints the same newline-delimited
+`terminal.frame` and `terminal.closed` records as observe mode. It reads
+newline-delimited JSON commands on stdin: `terminal.input`, `terminal.resize`,
+`terminal.scroll`, `terminal.mouse`, and `terminal.release`. One controller can
+own a terminal at a time; use `--takeover` to replace it.
+`terminal.mouse` sends one mouse event at a zero-based cell of the controller's
+viewport, for example
+`{"type":"terminal.mouse","action":"down","button":"left","column":12,"row":5}`.
+`action` is `down`, `up`, `drag`, or `move`; `button` is `left` (default),
+`right`, or `middle`; `modifiers` is optional and combines Shift = 1, Ctrl = 2,
+and Alt = 4 (default 0). A click is `down` followed by `up`. Herdr encodes the
+event for the application's mouse mode and drops it when the application has
+not enabled mouse reporting, so a plain shell never receives stray input.
+`move` reaches only applications that track all mouse motion.
+`terminal session observe` opens a read-only live terminal stream for a pane,
+terminal, or agent target. It prints newline-delimited JSON `terminal.frame`
+records with base64-encoded ANSI bytes, then a `terminal.closed` record when
+the server closes the stream. Multiple observers can watch the same terminal
+without taking input, resize, scroll, or takeover authority.
+On Linux and macOS, an observer is disconnected if a socket write makes no progress
+for 30 seconds. A stalled stream can end without a final `terminal.closed` record;
+the pane and other clients keep running. Quiet panes do not trigger this timeout.
+`terminal title clear` hands the outer terminal window title back to `ui.window_title`.
+
+## Output waits
+
+Wait for output in a pane:
+
+```bash
+herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--raw]
+```
+
+Use `pane wait-output` for normal commands and servers. Use `agent wait` for coding agents.
+
+`pane wait-output` checks the selected snapshot immediately, including output that already exists, then polls until it matches. The default source name is `recent`; matching treats it as unwrapped recent output from the latest 80 rendered terminal rows. `--lines` changes that row limit. `--match` finds a literal substring on one line, and `--regex` uses Rust regular-expression syntax and also matches one line at a time.
+
+A timeout or `agent_prompt_stalled` does not prove the prompt was never delivered. Inspect the agent before retrying.
+
+`pane wait-output` and `agent wait` wait indefinitely when `--timeout` is omitted. For `agent prompt --wait`, the settled-state wait is indefinite after activity is observed or when the prompt starts in `working`; a non-working prompt still returns `agent_prompt_stalled` after five seconds without observed activity. A timeout or server error is emitted as JSON on stderr with exit status 1. CLI usage errors exit with status 2.
+
+## Integrations
+
+```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 qwen
+herdr integration install letta
+herdr integration install cursor
+herdr integration install mastracode
+herdr integration install grok
+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 qwen
+herdr integration uninstall letta
+herdr integration uninstall cursor
+herdr integration uninstall mastracode
+herdr integration uninstall grok
+herdr integration status [--outdated-only]
+```
+
+## Plugins
+
+Plugin commands install and run local executable workflow plugins. A plugin is a manifest plus out-of-process commands; Herdr owns the host surface and plugins own their implementation language.
+
+Install, list, and remove plugins:
+
+```bash
+herdr plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]
+herdr plugin update [<plugin_id|owner/repo[/subdir...]>...] [--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` accepts GitHub shorthand only, such as `ogulcancelik/herdr-plugin-examples/worktree-bootstrap`. It uses `git`, shows a trust preview in interactive terminals, runs supported manifest build commands, and stores GitHub installs in a Herdr-managed directory. Use `--yes` for noninteractive installs. `plugin update` refreshes every GitHub-managed plugin when no targets are given, or only the listed plugin ids or GitHub sources. It preserves each install's requested ref, skips unchanged commits and ignores locally linked plugins during bulk updates. Reinstalling a GitHub-managed plugin creates a new installation directory. Running plugins keep their original files; new invocations use the new installation. Installing over a locally linked plugin is refused. Plugin manifests must declare `min_herdr_version`; install and link fail when the plugin requires a newer Herdr binary. `plugin list` is human-readable by default; pass `--json` for the raw API response.
+
+Plugin installation and enabled state are global to the current user. A plugin installed, linked, enabled, or disabled through one Herdr session is immediately available with the same state in every session.
+
+Local development:
+
+```bash
+herdr plugin link <path> [--disabled]
+herdr plugin unlink <plugin_id>
+```
+
+`plugin link` accepts a plugin directory containing `herdr-plugin.toml` or a direct manifest path. Use it while authoring or testing a plugin from a local checkout. `plugin unlink` and `plugin uninstall` unregister the plugin and leave files in place so running plugins can finish. Updates and reinstalls also retain previous installations; new invocations use the replacement without a config reload. A later successful installation/update or server startup removes obsolete managed installations after the servers using them have exited. Config reload does not release old installations. Plugins must stop detached background processes before their parent command or pane exits; processes surviving server exit are not protected from cleanup. Legacy installations without cleanup tracking and locally linked files are retained. For GitHub installs, uninstall accepts either the plugin id or the same `owner/repo[/subdir...]` shorthand used by install. Actions, event hooks, panes, and link handlers are declared in the manifest; runtime action registration is not part of v1.
+
+Config directory:
+
+```bash
+herdr plugin config-dir <plugin_id>
+```
+
+`plugin config-dir` prints the plugin's config directory. It creates the directory if needed and seeds it from legacy plugin config locations when present. Use it in setup docs and shell scripts to point users at a stable path for `.env` files and other user-editable config, separate from the managed plugin checkout.
+
+Actions:
+
+```bash
+herdr plugin action list [--plugin ID]
+herdr plugin action invoke <action_id> [--plugin ID]
+```
+
+`plugin action invoke` starts the manifest command for an installed, enabled,
+platform-compatible plugin action and prints the started command log record in
+the JSON response. Use the qualified action id (`plugin.id.action`) when more
+than one plugin uses the same action id. Local action ids cannot contain dots,
+so qualified ids remain unambiguous even when plugin ids contain dots.
+
+Logs:
+
+```bash
+herdr plugin log list [--plugin ID] [--limit N]
+```
+
+Managed terminal panes:
+
+```bash
+herdr plugin pane open --plugin ID --entrypoint ID [--placement overlay|popup|split|tab|zoomed] [--width SIZE] [--height SIZE] [--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` requires the plugin to be linked, enabled, and compatible
+with the current platform. It starts a manifest-declared `[[panes]]` command as
+a Herdr-managed terminal pane. The manifest default is `overlay`, which opens a
+temporary zoomed overlay over the active pane. It can also open as a split, a
+new tab, a zoomed pane, or a session-modal `popup` that does not change the tab
+layout. `--width` and `--height` set the outer popup dimensions in terminal
+cells or percentages such as `80%`; omitted dimensions default to half the
+terminal size, and values smaller than the popup minimum are clamped. A popup
+is not a Herdr pane, does not export `HERDR_PANE_ID`, and does not participate
+in pane or agent APIs. Native non-terminal plugin panes are outside plugin v1.
+
+New panes identify as `TERM_PROGRAM=herdr`, with `TERM_PROGRAM_VERSION` set to
+Herdr's version. They keep `TERM=xterm-256color` and `COLORTERM=truecolor`.
+They also get `fish_handle_reflow=0`, because Herdr reflows text on resize;
+an inherited or explicit `fish_handle_reflow` value is kept.
+Herdr removes inherited outer-terminal session markers (iTerm2, WezTerm, Kitty,
+Windows Terminal, tmux, screen, and Zellij), iTerm2's `LC_TERMINAL` identity,
+and known Claude Code, Codex, and OMP session markers before applying explicit
+launch environment values. This prevents new panes from claiming the terminal
+or agent session that originally started the server. Ordinary environment
+variables, including API keys and display settings, remain inherited rather than
+being replaced with the attaching client's environment. SSH-agent forwarding has
+its own reconnect handling. Existing pane processes are unchanged by this cleanup.
+
+`--env KEY=VALUE` can be repeated on process-launching commands. It applies to the newly launched process only. Herdr-managed variables such as `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`, and `HERDR_PLUGIN_CONTEXT_JSON` stay authoritative when they conflict with caller-provided env.
+
+## Read sources
+
+| Source | Meaning |
+| --- | --- |
+| `visible` | Current rendered screen. Best for UI feedback loops. |
+| `recent` | Recent scrollback with terminal wrapping. |
+| `recent-unwrapped` | Recent scrollback without soft wrapping. Best for logs. |
+| `detection` | Bottom-buffer snapshot used by agent screen detection. |
+
+These meanings apply to reads. For `pane wait-output` only, both `recent` and `recent-unwrapped` search the unwrapped recent snapshot; `recent` remains the default spelling.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `HERDR_CONFIG_PATH` | Override the config file path. |
+| `HERDR_SESSION` | Select a named session for CLI commands. |
+| `HERDR_SOCKET_PATH` | Low-level socket path override. |
+| `HERDR_PROCESS_DETECTION` | Linux process detection strategy: `native` (default) or opt-in `child-groups`. |
+| `HERDR_ENV` | Set to `1` inside Herdr-managed pane processes. |
+| `HERDR_PANE_ID` | Public pane id for the running pane process. |
+| `HERDR_TAB_ID` | Public tab id for the running pane process. |
+| `HERDR_WORKSPACE_ID` | Public workspace id for the running pane process. |
+| `HERDR_LOG` | Set log filter, for example `HERDR_LOG=herdr=debug`. |
+| `HERDR_DISABLE_SOUND` | Disable sound playback even when sound notifications are enabled. |
@@ -0,0 +1,89 @@
+---
+title: Concepts
+description: Understand Herdr workspaces, tabs, panes, agents, sessions, and modes.
+---
+
+Herdr is a terminal workspace manager. It keeps real terminal processes running and adds structure around them.
+
+## Workspace
+
+A workspace is the top-level project container. Use one workspace per repo, task, or investigation.
+
+A workspace owns tabs and panes. Its sidebar state rolls up from the agents inside it, so you can see which project needs attention.
+
+## Tab
+
+A tab is a layout inside a workspace. Use tabs to separate views like `agents`, `logs`, `server`, or `review`.
+
+Tabs are addressable from the CLI and socket API.
+
+## Pane
+
+A pane is a real terminal. Herdr renders the terminal output, sends input back to the process, and preserves the pane across client detach.
+
+Panes can be split right or down. They can be renamed manually, read from the CLI, sent input, and closed.
+
+## Mouse UI
+
+Herdr is mouse-native. You can click panes, tabs, workspaces, and agents. You can drag split borders, select text, and use right-click menus. Everything below is also reachable by mouse; keyboard bindings are an optional layer.
+
+If you prefer keyboard-only control, or you want Herdr to stop capturing mouse input, disable mouse capture:
+
+```toml
+[ui]
+mouse_capture = false
+```
+
+## Agent
+
+An agent is a process Herdr recognizes inside a pane. Herdr detects agents from foreground processes, screen manifests, and optional integrations.
+
+Agent states are:
+
+| State | Meaning |
+| --- | --- |
+| `blocked` | The agent needs input, approval, or a decision. |
+| `working` | The agent is actively running. |
+| `done` | The agent finished and you have not looked at it yet. |
+| `idle` | The agent is finished or waiting and has been seen. |
+| `unknown` | Herdr cannot confidently classify the state. |
+
+Each client tracks which completions it has displayed. Viewing a completion in one client does not clear another client's Done badge. CLI/API statuses use the server's seen state, so they need not match a particular client's badge; both `idle` and `done` mean ready for input.
+
+## Session
+
+A session is a persistent Herdr server namespace. The default `herdr` command attaches to the default session.
+
+Named sessions are separate runtime namespaces:
+
+```bash
+herdr session list
+herdr session attach work
+herdr session attach side-project
+```
+
+Use workspaces first. Use named sessions when you need completely separate panes, sockets, and persisted runtime state.
+
+## Client and server
+
+By default, Herdr runs as a background server plus one or more attached clients.
+
+The server owns panes and process state. The client is the terminal UI attached to that server.
+
+With one attached client, all tabs follow its size as before. With multiple clients, each can view its own workspace and tab. Different viewed tabs follow their respective clients; when clients view the same tab, the last one to focus, select, or interact with it controls that tab's pane sizes.
+
+Detach the client with `ctrl+b q`. The server and agents continue running.
+
+If you want to end the session and stop its panes, stop the server:
+
+```bash
+herdr server stop
+```
+
+## Modes
+
+Herdr has terminal mode, prefix mode, and navigate mode.
+
+Terminal mode sends keys to the focused pane. Prefix mode waits for one Herdr action after the prefix key. Navigate mode is the persistent workspace navigation surface.
+
+Press the prefix key, default `ctrl+b`, then an action key such as `c` for a new tab or `w` for workspace navigation. See [Keyboard](/docs/keyboard/) if the prefix idea is new to you.
@@ -0,0 +1,21 @@
+---
+title: Config reference
+description: Every canonical config.toml key, with types, defaults, and allowed values.
+---
+
+import ConfigReference from '../../components/ConfigReference.astro';
+
+Browse every canonical key Herdr reads from `config.toml` in a flat, filterable list. For setup guidance
+and the reasoning behind these options, see [Configuration](/docs/configuration/).
+
+Print the full commented default config at any time:
+
+```bash
+herdr --default-config
+```
+
+Custom command bindings (`[[keys.command]]`) are user-defined tables and are not
+listed per key here; see
+[Custom command keybindings](/docs/configuration/#custom-command-keybindings).
+
+<ConfigReference />
@@ -0,0 +1,615 @@
+---
+title: Configuration
+description: Configure Herdr keybindings, themes, sidebar behavior, notifications, and advanced options.
+---
+
+Herdr works without a config file. Add one when you want custom keys, themes, sidebar layouts, notifications, or advanced behavior.
+
+The [Config reference](/docs/config-reference/) lists every setting and keybinding, with types, defaults, and allowed values. This page covers setup, common recipes, and configuration structures that need more explanation than a reference row.
+
+## Config file
+
+Herdr reads config from:
+
+```text
+Linux and macOS: ~/.config/herdr/config.toml
+Windows:          %APPDATA%\herdr\config.toml
+```
+
+Run `herdr --help` to see the resolved config path for your system.
+
+Print the full default config:
+
+```bash
+herdr --default-config
+```
+
+Save it as your config if you want a complete starting point:
+
+```bash
+herdr --default-config > ~/.config/herdr/config.toml
+```
+
+If a config value is invalid, Herdr falls back to a safe default and shows a startup warning.
+
+Herdr shows first-run setup when `onboarding` is missing or true. Continuing from onboarding writes `onboarding = false` and opens settings on the integrations tab. Set `onboarding = false` to skip that flow after setup.
+
+```toml
+onboarding = false
+```
+
+## Reload config
+
+Reload a running server after editing `config.toml`:
+
+```bash
+herdr server reload-config
+```
+
+You can also open the global menu in Herdr and choose `reload config`.
+
+Reload applies most UI settings without restarting panes. Startup-only settings still need a restart.
+
+Themes, sidebar layouts, copy behavior, and other presentation settings come from the client's local config, including when viewing an SSH machine. Pane defaults, worktrees, integrations, and custom commands belong to the server where the panes run. The UI's `reload config` action reloads both the client's local settings and the selected server's config. Local keybindings reload too; `--remote-keybindings server` instead uses the selected server's keybindings.
+
+## Headless terminal size
+
+When no client is attached, the server uses a 120×40 virtual terminal for layout and newly created panes. Change that fallback for headless orchestration with:
+
+```toml
+[server]
+headless_cols = 160
+headless_rows = 50
+```
+
+With one attached client, all tabs follow its size. With multiple clients, each viewed tab follows the client that most recently focused, selected, or interacted with it. When all but one client detach, all tabs immediately return to the remaining client's size. When no clients remain, existing pane PTYs retain their last size and new headless layout uses the configured fallback.
+
+## Terminal defaults
+
+Set the executable Herdr uses for newly created interactive panes:
+
+```toml
+[terminal]
+default_shell = "nu"
+```
+
+When unset or empty, Herdr uses `$SHELL`, then `/bin/sh` on Unix. On Windows it uses `pwsh.exe` (PowerShell 7) when it resolves on `PATH`, and otherwise the inbox `powershell.exe` (Windows PowerShell 5.1). This is an executable name or path, not a shell command line. Existing panes keep their current shell until they are recreated. Custom command keybinding strings run through `/bin/sh -c` for pane commands and `/bin/sh -lc` for detached commands on Unix; on Windows they run through `cmd.exe /d /c`.
+
+Set how Herdr starts newly created interactive pane shells:
+
+```toml
+[terminal]
+shell_mode = "auto"
+```
+
+`shell_mode = "auto"` starts login shells on macOS so login-only PATH setup such as `/usr/libexec/path_helper` and Homebrew shell initialization runs in new panes. On other platforms, it keeps the existing non-login shell behavior. Use `"login"` to force login-shell startup or `"non_login"` to force non-login startup. Command panes, detached custom command keybindings, and explicit argv launches keep their existing command execution paths.
+
+Set the working directory policy for new panes, tabs, and workspaces:
+
+```toml
+[terminal]
+new_cwd = "follow"
+```
+
+`new_cwd = "follow"` keeps the default behavior and inherits the source pane or workspace. When there is no source workspace, Herdr starts in `$HOME`. Use `"home"` to always start in `$HOME`, `"current"` to use Herdr's process directory, or a fixed path such as `"~/Projects"`. Explicit `--cwd` values from the CLI or socket API still take precedence.
+
+## Worktrees
+
+Set the root directory Herdr uses for Git worktree checkouts created from the sidebar:
+
+```toml
+[worktrees]
+directory = "~/.herdr/worktrees"
+```
+
+Herdr creates checkouts under `<directory>/<repo>/<branch-slug>`. For sibling-style checkouts, set this to a directory such as `~/Projects/herdr-worktrees`. Relative values are resolved to an absolute path when the app applies the config.
+
+Worktree actions are available from Git workspace rows. `New worktree` creates a checkout. It checks out an existing local branch when the entered branch exists; otherwise, it creates the branch. It then opens the checkout as a new Herdr workspace and groups it under the source workspace. `Open worktree...` lists existing Git worktree checkouts for that repo. Choosing an already-open checkout focuses it, while choosing a closed checkout opens it in the same group.
+
+Grouped worktrees still behave like normal Herdr workspaces: they can be focused, renamed, closed, and contain their own tabs and panes. The parent row is the original workspace. Closing the parent row closes the whole Herdr group, but it does not delete checkout folders or branches.
+
+To delete a worktree checkout, use `Delete worktree checkout...` on a grouped child workspace. Herdr runs `git worktree remove`, first asking Git to remove safely. If Git refuses because the checkout has modified or untracked files, Herdr asks again before running the forced remove. Branches are not deleted.
+
+## Remote attach
+
+Remote attach manages its SSH connection with temporary keepalives and, where supported, connection reuse by default.
+
+```toml
+[remote]
+manage_ssh_config = true
+```
+
+When enabled, `herdr --remote` writes a private temporary SSH config that includes your user and system SSH configs first, then adds fallback `ServerAliveInterval` and `ServerAliveCountMax` values. Your own keepalive settings win. Linux and macOS clients also use a private per-attach OpenSSH control socket to reuse the first authenticated connection; Windows OpenSSH does not. Set `manage_ssh_config = false` to run remote attach through plain `ssh` without Herdr's generated config or control socket.
+
+## Keybindings
+
+For a guided introduction to the prefix and a vetted prefix-free setup, see [Keyboard](/docs/keyboard/).
+
+Herdr has a prefix mode similar to tmux. The default prefix is `ctrl+b`. Keybinding strings are explicit: `prefix+n` means press the configured prefix and then `n`; `ctrl+alt+n` is a direct terminal-mode shortcut.
+
+A small keybinding override looks like this:
+
+```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"
+```
+
+`keys.prefix` also accepts an array when you need to enter prefix mode from more than one key, for example to share one config between macOS and a remote Linux machine:
+
+```toml
+[keys]
+prefix = ["ctrl+space", "ctrl+s"]
+```
+
+Every configured prefix enters the same prefix mode and starts every `prefix+...` action. The first entry is the primary prefix shown in the status bar; the in-app help panel at `prefix+?` lists all of them.
+
+The default keymap is prefix-first so Herdr does not steal input from shells, editors, tmux, or terminal apps. Search `keys.` in the [Config reference](/docs/config-reference/) to see every action and default binding. The in-app help panel at `prefix+?` shows the active bindings.
+
+A binding may also be an array when one action needs multiple shortcuts:
+
+```toml
+[keys]
+next_tab = ["prefix+n", "ctrl+alt+]"]
+```
+
+Optional actions are unset by default. Bind them with `prefix+` for prefix-mode behavior, or use an explicit modified chord when you intentionally want a direct shortcut. For example, tmux-style one-keystroke pane resizing without entering resize mode:
+
+```toml
+[keys]
+resize_pane_left = "ctrl+shift+alt+left"
+resize_pane_down = "ctrl+shift+alt+down"
+resize_pane_up = "ctrl+shift+alt+up"
+resize_pane_right = "ctrl+shift+alt+right"
+```
+
+Key strings accept plain keys, modifier combinations such as `ctrl+a`, `shift+n`, `alt+1`, `cmd+k`, and special keys such as `enter`, `tab`, `esc`, `left`, `right`, `up`, and `down`. Named punctuation such as `minus`, `comma`, `ampersand`, `plus`, and `backtick` is also accepted. Plain direct printable keys such as `n` are unsafe because they intercept typing; use `prefix+n` unless you intentionally want a direct binding. The `navigate_workspace_*` and `navigate_pane_*` fields are navigate-mode-only and may use plain keys such as `j` or `k`; they must not use `prefix+`, `esc`, `enter`, `tab`, `shift+tab`, `left`, `right`, or unmodified `1` through `9`. Left and right arrows are permanent aliases for pane-left and pane-right navigation. These navigate-mode shortcuts are independent from general action bindings such as `focus_pane_down = "prefix+j"`; when both use the same key, the navigate-mode shortcut wins while navigate mode is open. Alt, Cmd/Super, and punctuation with modifiers depend on your terminal and tmux settings.
+
+If you have old custom keybindings and want the new defaults, run `herdr config reset-keys`. Herdr backs up `config.toml`, removes `[keys]` and `[[keys.command]]`, and uses built-in v2 defaults after restart or `herdr server reload-config`.
+
+## Indexed jumps
+
+Indexed keybindings use `1..9` in normal keybinding fields:
+
+```toml
+[keys]
+switch_tab = "prefix+1..9"
+switch_workspace = "prefix+shift+1..9"
+focus_agent = "prefix+alt+1..9"
+```
+
+The legacy `[keys.indexed]` table is still parsed for compatibility, but new configs should prefer the explicit action fields.
+
+## Custom command keybindings
+
+Custom commands use the same keybinding syntax.
+
+```toml
+[[keys.command]]
+key = "prefix+alt+g"
+type = "popup"
+command = "lazygit"
+description = "run lazygit"
+width = "80%"
+height = "80%"
+```
+
+`type = "popup"` opens a session-modal popup without changing the tab layout.
+The popup receives all terminal input, including Escape, until its command
+exits. `width` and `height` are optional; omit them for the default half-size
+popup, use numbers for terminal cells, or use strings like `"80%"` for a
+percentage of the terminal area. Dimensions include the popup border, and
+values smaller than the popup minimum are clamped. Popup commands do not receive
+`HERDR_PANE_ID`; use `HERDR_ACTIVE_PANE_ID` for the underlying tiled pane.
+
+On Unix and macOS, a popup command can also provide an ad-hoc terminal without
+adding a split or tab:
+
+```toml
+[[keys.command]]
+key = "prefix+t"
+type = "popup"
+command = "exec \"${SHELL:-sh}\""
+description = "open scratch terminal"
+width = "80%"
+height = "80%"
+```
+
+On Windows, use a shell command such as `command = "powershell.exe -NoLogo"`
+instead. Exit the shell to close the popup and restore the tiled terminal view.
+
+`type = "pane"` opens a temporary zoomed pane and closes it when the command exits.
+
+`type = "shell"` runs detached in the background.
+
+`type = "plugin_action"` invokes an installed plugin action id. Use the
+qualified id when action ids are not globally unique:
+
+```toml
+[[keys.command]]
+key = "prefix+l"
+type = "plugin_action"
+command = "example.layout.apply"
+description = "apply layout"
+```
+
+`description` is optional. When set, it appears in the keybind help panel (opened with `prefix+?`) instead of the default `'custom command'` label.
+
+Custom commands receive `HERDR_SOCKET_PATH`, `HERDR_BIN_PATH`, `HERDR_ACTIVE_WORKSPACE_ID`, `HERDR_ACTIVE_TAB_ID`, `HERDR_ACTIVE_PANE_ID`, and `HERDR_ACTIVE_PANE_CWD` when those values are available. Shell commands run from the focused pane's working directory when Herdr can detect it.
+
+On Windows, custom command strings use `cmd.exe /d /c`, so environment variables use `%HERDR_BIN_PATH%` syntax. To run PowerShell syntax, invoke it explicitly, for example `powershell.exe -NoProfile -Command "..."`.
+
+## Theme
+
+Choose a built-in theme:
+
+```toml
+[theme]
+name = "catppuccin"
+```
+
+Search `theme.name` in the [Config reference](/docs/config-reference/) for every built-in theme. Use `terminal` when you want Herdr UI colors to follow your host terminal's ANSI palette.
+
+On Unix, Herdr also re-reads the host terminal's colors when redrawing after a resize or `SIGWINCH`. If your theme switcher changes terminal colors through OSC without a light/dark notification, send `kill -WINCH <client-pid>` after applying the new palette. Target the attached Herdr client, not the server; existing panes stay running. Direct `herdr terminal attach` sessions leave palette queries to the attached application.
+
+To let Herdr switch its own UI theme when the host terminal reports a light/dark appearance change, enable theme auto-switching:
+
+```toml
+[theme]
+name = "catppuccin"
+auto_switch = true
+light_name = "catppuccin-latte"
+dark_name = "catppuccin"
+```
+
+`auto_switch` defaults to `false`, so existing theme configs keep manual behavior. If `light_name` or `dark_name` is omitted, Herdr uses the matching built-in sibling for the configured `name` when one exists, such as `tokyo-night`/`tokyo-night-day` or `gruvbox`/`gruvbox-light`. Manual theme selection in Settings disables `auto_switch`.
+
+You can override individual colors:
+
+```toml
+[theme.custom]
+sidebar_bg = "#181825"
+active_row_bg = "#1e1e2e"
+selection_bg = "#313244"
+panel_bg = "reset"
+accent = "#a6e3a1"
+green = "#a6e3a1"
+blue = "#89b4fa"
+red = "#f38ba8"
+yellow = "#f9e2af"
+```
+
+`sidebar_bg` optionally gives the desktop sidebar its own background. When omitted, the sidebar keeps the host terminal background. `active_row_bg` changes the active Space and focused Agent row background without affecting separators or scrollbar tracks. `selection_bg` changes the Navigate-mode cursor row background in the sidebar.
+
+Color values accept hex, named colors, `rgb(r,g,b)`, or reset aliases like `reset`, `default`, `none`, and `transparent`.
+
+When `auto_switch` is enabled, optional light and dark subtables layer on top of the shared custom colors:
+
+```toml
+[theme.custom]
+accent = "#89b4fa"
+
+[theme.custom.light]
+panel_bg = "#eff1f5"
+text = "#4c4f69"
+
+[theme.custom.dark]
+panel_bg = "#1e1e2e"
+text = "#cdd6f4"
+```
+
+The active palette is applied in this order: built-in theme, `[theme.custom]`, then `[theme.custom.light]` or `[theme.custom.dark]`. Omitting the mode subtables preserves the existing shared override behavior.
+
+## UI and sidebar
+
+The sidebar is the main Herdr dashboard. Search `ui.` in the [Config reference](/docs/config-reference/) for sizing, collapsed mode, Agent panel ordering, mouse behavior, pane borders, and other presentation settings.
+
+`ui.pane_borders` accepts `"auto"` (the default, borders only for split panes), `"always"` (also frame a single pane), or `"off"`. A single-pane frame requires `ui.pane_outer_borders = true`, because all its edges are outer edges. Existing boolean values remain valid: `true` means `"auto"` and `false` means `"off"`.
+
+Set `tab_bar_position = "bottom"` under `[ui]` to place the desktop tab row below the terminal panes. Prefix, Navigate, Copy, and Resize mode bars temporarily replace the bottom tab row while active. The default is `"top"`.
+
+Configure an ordered tmux-style status area at the right edge of the tab row:
+
+```toml
+[ui]
+tab_bar_right = [
+  { type = "zoom" },
+  { type = "hostname" },
+  { type = "datetime", format = "%H:%M" },
+  { type = "text", text = "prod" },
+  { type = "command", command = "~/.config/herdr/status.sh", interval_seconds = 5, timeout_seconds = 2 },
+]
+tab_bar_right_separator = " · "
+```
+
+The status area is empty by default. Add `zoom` to show a fixed `ZOOM` pill while the active tab is zoomed; the existing per-tab `Z` markers remain independent. `hostname`, `datetime`, and `command` resolve on the Herdr server, so `herdr --remote` shows the remote machine's values. Datetime entries use `strftime` formatting; directives that require a UTC offset or Unix timestamp, such as `%z` and `%s`, are rejected because the value is server-local wall-clock time.
+
+Command entries run immediately and then at `interval_seconds` without blocking rendering or overlapping a previous run. The interval can be 1–31,536,000 seconds and the timeout can be 1–3,600 seconds. Herdr uses the last line of successful output, removes ESC-prefixed terminal control sequences instead of interpreting styles, clears the entry after failure, empty output, or `timeout_seconds`, and provides the same active workspace, tab, pane, socket, binary, and working-directory context as custom command keybindings. Commands are supported on Linux, macOS, and Windows, using `/bin/sh -lc` on Linux and macOS and `cmd.exe /d /c` on Windows.
+
+Separators appear only between visible entries. Set `tab_bar_right_separator = ""` for direct concatenation. On a narrow tab row, the complete status area yields to the tabs and their controls.
+
+### Outer terminal window title
+
+Herdr emulates the terminals in its panes, so an `OSC 0`/`OSC 2` title written inside a pane stops at Herdr. Herdr writes its own title to the terminal it runs in, which is what window managers and terminal tab bars read:
+
+```toml
+[ui]
+window_title = "{hostname}: {workspace}"
+```
+
+Tokens are `{hostname}`, `{workspace}`, `{tab}`, `{pane}` (the focused pane's manual name), and `{terminal_title}` (the focused pane's own terminal title with spinner frames stripped). Write `{{` and `}}` for literal braces. A token with no value renders empty.
+
+The title renders on the Herdr server, so `{hostname}` names the machine the panes run on, including when you attach with `herdr --remote` or run `herdr` over SSH. Set `window_title = ""` to leave the outer terminal title alone.
+
+`client.window_title.set` overrides the configured title until `client.window_title.clear` hands it back.
+
+Agent status uses compact colored dots by default. To distinguish blocked, working, done, idle, and unknown states by shape as well as color, choose **distinct symbols** in Settings or configure:
+
+```toml
+[ui]
+status_indicators = "symbols"
+```
+
+The symbols are static, so this option does not enable spinner animation.
+
+### Sidebar row layouts
+
+The expanded desktop sidebar renders each inner array in `rows` as one line. These are the complete default layouts:
+
+```toml
+[ui.sidebar.agents]
+row_gap = 0
+rows = [
+  ["state_icon", "machine", "workspace", "tab"],
+  ["agent"],
+]
+
+[ui.sidebar.spaces]
+row_gap = 0
+rows = [
+  ["state_icon", "workspace"],
+  ["branch", "git_status"],
+]
+```
+
+Agent rows accept these built-in tokens:
+
+- `state_icon` — colored icon for the agent's semantic state.
+- `state_text` — `idle`, `working`, `blocked`, `done`, or `unknown`, including a reported display label when present.
+- `machine` — machine label when the client has multiple machines; omitted for a single local machine.
+- `workspace` — workspace name.
+- `tab` — tab name when available.
+- `pane` — pane name when available.
+- `agent` — detected or reported agent display name.
+- `terminal_title` — latest OSC 0/2 terminal title after safety normalization.
+- `terminal_title_stripped` — the terminal title with one recognized leading activity or spinner glyph and its following whitespace removed.
+- `$name` — custom pane metadata named `name`.
+
+Space rows accept these built-in tokens:
+
+- `state_icon` — colored icon for the space's rolled-up agent state.
+- `state_text` — text for the rolled-up agent state.
+- `workspace` — workspace name.
+- `branch` — Git branch when available.
+- `git_status` — Git ahead and behind counts when nonzero.
+- `$name` — custom workspace metadata named `name`.
+
+Tokens render in their configured order. Herdr normally separates adjacent values with ` · ` and uses a single space after `state_icon`. Missing values and their separators disappear; a row disappears when none of its tokens have a value. Existing custom rows remain unchanged, so add `machine` explicitly if you want machine identity in a custom multi-machine layout. Each layout may contain at most 16 rows, with at most 16 tokens in each row.
+
+A token entry can also be an inline style table:
+
+```toml
+[ui.sidebar.agents]
+rows = [
+  ["state_icon", { token = "workspace", bold = false }, "tab"],
+  [{ token = "$summary", fg = "#89b4fa", bold = true, dim = false }],
+]
+```
+
+`fg` accepts strict `#RGB` or `#RRGGBB`. `bold` and `dim` accept booleans. Omitted fields preserve the token's contextual style; explicit `false` removes that modifier. Styling applies to one occurrence, so the same token may look different in another row or agent override. A foreground override replaces all semantic foregrounds inside that occurrence: for example, styled `git_status` ahead and behind counts use one color instead of their default green and red. Token styles never change separators or row backgrounds.
+
+Text-valued tokens also accept up to 16 ordered `rules`. Each rule contains exactly one condition—`equals`, `contains`, `starts_with`, `gt`, or `lt`—and optional `fg`, `bold`, and `dim` overrides:
+
+```toml
+[ui.sidebar.agents]
+rows = [
+  ["state_icon", "workspace", "tab"],
+  [{ token = "machine", fg = "#fff", rules = [{ equals = "Local", fg = "#f55" }, { equals = "Fedora", ignore_case = true, fg = "#51a2da" }] }, "agent"],
+  [{ token = "$load", fg = "#fff", rules = [{ gt = 80, fg = "#f55", bold = true }, { gt = 50, fg = "#fc0" }] }],
+]
+```
+
+The first matching rule wins. Its specified style fields override the occurrence's defaults; unspecified fields inherit them. If no rule matches, the defaults remain. Matching uses the full token value before display truncation. Set `hide = true` on a rule to remove the matching token and its separator; rows with no remaining tokens also disappear. For example, `{ token = "machine", fg = "#61afef", rules = [{ equals = "Local", hide = true }] }` hides the machine token when its label is exactly `Local`. This compares the label, not the connection type. With `hide = false` or omitted, the token stays visible. A rule with no overrides still stops matching and keeps the defaults.
+
+`equals`, `contains`, and `starts_with` take strings and are case-sensitive. Add `ignore_case = true` for ASCII case-insensitive matching; non-ASCII characters remain case-sensitive. Empty strings follow ordinary string matching: empty `equals` matches only an empty value, while empty `contains` or `starts_with` matches any present value.
+
+`gt` and `lt` take finite numeric thresholds and compare strictly greater or less, not equal. Values must parse completely as finite numbers; decimal and exponent forms work, but whitespace, units, `NaN`, and infinity do not match. `ignore_case` is not accepted on numeric rules. Comparisons use floating-point numbers, not exact large-integer arithmetic.
+
+Rules work with text-valued built-ins and custom `$name` tokens in Agent rows, `rows_by_agent` overrides, and Space rows. Custom tokens match their reported value: `$load` reporting `"90"` selects red and bold above, `"60"` selects yellow, and `"90%"` keeps white. Unreported tokens still disappear. `state_icon` and composite `git_status` accept fixed styles only, not rules. Unknown conditions and malformed rules are rejected when loading config; regex, fuzzy matching, and scripts are not supported.
+
+`row_gap` controls the blank terminal rows between entries, independently for the Agent and Space panels. It defaults to `0`, which packs entries together; set it to `1` to restore the previous spacing. It does not add spacing between the content lines declared in `rows`. Consecutive indented worktree children remain packed as one Space group.
+
+Override the complete Agent layout for a known agent under `rows_by_agent`:
+
+```toml
+[ui.sidebar.agents]
+rows = [
+  ["state_icon", "agent", "state_text"],
+  ["workspace", "tab"],
+]
+
+[ui.sidebar.agents.rows_by_agent]
+claude = [
+  ["state_icon", "agent", "state_text"],
+  ["terminal_title_stripped"],
+  ["workspace", "tab"],
+]
+```
+
+An override replaces `rows`; it does not extend it. Override keys are case-sensitive canonical agent IDs such as `claude`, `codex`, and `pi`. Detection aliases such as `claude-code` are not accepted. Agents without an override, including custom reported agents, use `rows`.
+
+Custom `$name` tokens are dynamic values, not literal text. Add the token to a layout, then report its value from a script or plugin:
+
+```toml
+[ui.sidebar.agents]
+rows = [
+  ["state_icon", "agent", "$model"],
+  ["$summary"],
+  ["workspace", "tab"],
+]
+```
+
+```bash
+herdr pane report-metadata <pane_id> \
+  --source my-agent-hook \
+  --token model=opus \
+  --token summary="reviewing authentication"
+```
+
+Use `herdr workspace report-metadata` in the same way for custom Space tokens. Unreported custom tokens disappear.
+
+Metadata reporters provide values only; styling stays in the local sidebar configuration. See [CLI reference: report metadata](/docs/cli-reference/#panes) for limits, clearing, sequencing, and expiry.
+
+Sidebar row settings affect only the expanded desktop sidebar. Collapsed and mobile views keep their compact layouts.
+
+## Notifications
+
+Herdr can notify you when a background agent finishes or needs input:
+
+```toml
+[ui.toast]
+delivery = "herdr"
+delay_seconds = 1
+
+[ui.toast.herdr]
+position = "bottom-right"
+```
+
+Choose `herdr` for an in-app toast, `terminal` for an outer-terminal notification that also works over SSH, `system` for the local OS notification service, or `off` to disable popups. Herdr suppresses popups for the active tab. Search `ui.toast` in the [Config reference](/docs/config-reference/) for positions, delay behavior, and clipboard feedback settings.
+
+On macOS, `system` tries `terminal-notifier` first and falls back to `/usr/bin/osascript` when it is unavailable or fails. The fallback appears as Script Editor in Notification Center and cannot activate the hosting terminal. Install `terminal-notifier` with `brew install terminal-notifier`. For a supported, detected terminal, it can activate the terminal app when you click the notification. Alternatively, choose `terminal` to let a supported outer terminal own the notification.
+
+On Windows, `system` notifications remain in Notification Center. Clicking one selects its originating pane in the running Herdr client and brings its terminal window forward when Windows exposes that window. A click cannot reopen a closed client or select a pane from a restarted server. Windows Terminal can bring the owning window forward, but cannot reliably select a different outer terminal tab.
+
+## Sound
+
+Sound notifications play through the local Herdr client. Custom sounds must be mp3 files; Herdr resolves relative paths from the config file's directory.
+
+```toml
+[ui.sound]
+path = "sounds/notification.mp3"
+done_path = "sounds/done.mp3"
+request_path = "sounds/request.mp3"
+```
+
+`path` sets one sound for all sound notifications. `done_path` and `request_path` override only the finished and needs-input sounds.
+
+Per-agent sound overrides accept `default`, `on`, or `off`. Use detected agent labels such as `claude`, `codex`, `devin`, or `droid` as keys. Droid is muted by default.
+
+```toml
+[ui.sound.agents]
+droid = "off"
+claude = "on"
+```
+
+## Advanced configuration
+
+Search the [Config reference](/docs/config-reference/) for scrollback limits, nested launches, and other advanced or experimental settings. See [Session state and restore](/docs/session-state/) before enabling pane screen history; that guide explains the security trade-off of saving pane contents.
+
+## Kitty graphics
+
+Applications and plugins integrate through the standard Kitty graphics protocol emitted in pane terminal output. Herdr renders these images by default in compatible outer terminals. The external socket pane-overlay API has been removed; there is no replacement socket image API.
+
+Popups, menus, and notifications crop images around the area they cover; the rest of each image stays visible and the covered part returns when the overlay closes. Images do not dim with dialog backgrounds.
+
+Herdr automatically chooses eligible file transports, with no application changes or environment switches. On local Unix Ghostty clients, it can send image data through temporary files instead of encoding it into terminal output. A small file-consumption probe checks support first. Other terminals, SSH-launched clients, and nested multiplexers retain inline output for this last-hop optimization.
+
+For eligible local clients, native RGBA images travel from server to client as paths to Herdr-owned snapshots rather than pixel bytes. Unsupported clients and failed transfers fall back to inline delivery. Remote server paths are never forwarded to the local terminal. Herdr keeps image placement, clipping, and visibility under its control.
+
+On Linux, whole-file, uncompressed RGBA uploads can use copy-on-write snapshots before Herdr reads their pixels. This requires filesystem support for cloning into Herdr's private `/var/tmp` store. Unsupported filesystems, temporary-file uploads, shared memory, and other formats use the normal loader. Snapshots are limited to 16 MiB each and 64 MiB total; animation and unsupported clients read their pixels when needed. Herdr never relies on a mutable producer path after accepting an image.
+
+PNG uploads retain full decoding and validation. Herdr does not defer corrupt-image validation to the outer terminal.
+
+To disable Kitty graphics rendering:
+
+```toml
+[terminal]
+kitty_graphics = false
+```
+
+The legacy `experimental.kitty_graphics` setting remains accepted for existing configurations. `terminal.kitty_graphics` takes precedence when both are set.
+
+Changing this setting requires restarting the affected Herdr server or reattaching the client. In remote sessions, the server's setting controls Kitty graphics parsing, while the local client's setting controls output to the outer terminal.
+
+## Agent session restore
+
+Herdr resumes supported Agent conversations after a server restart by default:
+
+```toml
+[session]
+resume_agents_on_restore = true
+startup_per_agent_delay_ms = 100
+```
+
+Automatic restores start one agent at a time, 100 milliseconds apart by default, to reduce startup contention. The first eligible agent starts immediately. Set `startup_per_agent_delay_ms = 0` to disable spacing. Manual launches and explicit terminal attaches are unaffected. Restart the Herdr server to apply changes.
+
+Only panes with a valid native session reference from an official integration can resume; other panes restore as normal shells. See [Session state and restore](/docs/session-state/) for supported Agents and persistence behavior.
+
+## IME cursor tracking
+
+On macOS, AI Agent TUIs that hide the hardware cursor can prevent native input-method candidate windows from following the focused pane. Reveal a cursor anchor for those panes with:
+
+```toml
+[experimental]
+reveal_hidden_cursor_for_cjk_ime = true
+cjk_ime_agents = ["claude", "pi", "codex"]
+```
+
+Restricting `cjk_ime_agents` avoids showing an extra hardware cursor in unrelated applications. Search these keys in the [Config reference](/docs/config-reference/) for accepted Agent names and cursor shapes.
+
+## Prefix input source switching
+
+On macOS and Windows, Herdr can temporarily switch to an ASCII-capable input source while prefix commands and prefix-launched modes are active:
+
+```toml
+[experimental]
+switch_ascii_input_source_in_prefix = true
+```
+
+On macOS this switches to the current ASCII-capable keyboard layout; on Windows it switches the IME to English (ASCII) input. Herdr restores the previous input source when returning to terminal input or entering a text field. This setting has no effect on other platforms.
+
+:::caution[Windows support is Korean IME only]
+On Windows, support is currently limited to the Korean IME. With an IME for any other language, this setting leaves the input source unchanged.
+:::
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `HERDR_CONFIG_PATH` | Override the config file path. |
+| `HERDR_SESSION` | Select a named session for CLI commands. |
+| `HERDR_SOCKET_PATH` | Low-level socket path override. |
+| `HERDR_PROCESS_DETECTION` | Linux process detection strategy: `native` (default) or opt-in `child-groups`. |
+| `HERDR_LOG` | Set log filtering, for example `HERDR_LOG=herdr=debug`. |
+| `HERDR_DISABLE_SOUND` | Disable sound playback even when `[ui.sound] enabled = true`. |
+
+## Logs
+
+Logs are useful when diagnosing startup warnings, integration state, or socket API behavior.
+
+Common log files:
+
+```text
+~/.config/herdr/herdr.log
+~/.config/herdr/herdr-client.log
+~/.config/herdr/herdr-server.log
+```
+
+Logs rotate automatically. Include the current log and rotated siblings when reporting issues.
@@ -0,0 +1,128 @@
+---
+title: Connecting machines
+description: Work across Local and saved SSH machines in one Herdr window, with shared agent navigation and independent reconnects.
+---
+
+Keep your local work and remote agents in one Herdr window. Save an SSH machine once, then switch between its workspaces and Local without opening another client. The agent list includes connected machines, so you can see where work is running and which agent needs an answer.
+
+Each machine keeps its own Herdr server, sessions, and running processes. A lost connection to one machine does not disconnect the others.
+
+Herdr requests SSH compression to reduce screen-update traffic on limited connections. This works with older compatible Herdr servers and does not change how typing or other input is delivered. Herdr's `-C` option overrides `Compression no` in your SSH config. If SSH reuses an existing connection through an external ControlMaster, that connection keeps its original compression setting.
+
+### Recovering SSH authentication
+
+On Linux and macOS clients, when `remote.manage_ssh_config=true`, Herdr shares an approved OpenSSH connection across machine add, the sidebar, and saved-machine API commands. Run `herdr machine status [<label-or-id>] [--json]` for fresh, noninteractive checks. **Reachable** means the remote Herdr server is available now, not that every open TUI is connected. Run `herdr machine reconnect <label-or-id>` in a terminal to complete native SSH authentication and verify the saved machine. It does not install or update Herdr. Open clients recheck failed connections within 30 seconds; no restart is needed. Clicking **`! auth`**, **`! error`**, or a failed connection's reconnecting status shows a notice with its latest error and the relevant CLI command. It never opens a credential popup. The rest of the machine row keeps its normal expand/collapse behavior.
+
+The shared connection uses `ControlPersist 600` (10 minutes of idle time); this is not MFA validity. Active connections can remain open, while corporate policy, the SSH server, or the network may end them sooner. Local Windows recovery is not supported yet. For unmanaged SSH connections, authentication remains your responsibility: running `ssh` by itself does not grant Herdr approval unless it uses the shared ControlPath. Host-key checking is unchanged; an unknown or changed host key remains **Attention**.
+
+## Before you connect
+
+You need normal SSH access to the remote machine. Verify it first:
+
+```bash
+ssh workbox
+```
+
+`workbox` can be a host from your SSH config. You can also use a target such as `ssh://you@server:2222`.
+
+Multi-machine connections support Linux, macOS, and Windows clients connecting to Linux or macOS servers on x86_64 or aarch64, or Windows servers on x86_64. Interactive setup can install or update the complete remote package after confirmation; background reconnects only discover installed packages. See [Remote attach over SSH](/docs/persistence-remote/#remote-attach-over-ssh) for SSH configuration, authentication, and custom binaries.
+
+## Add a machine
+
+Run setup in an interactive terminal so Herdr can ask before installing or replacing anything:
+
+```bash
+herdr machine add workbox
+```
+
+In an interactive terminal, Herdr discovers running sessions: it selects the only running session, or lets you choose with Up/Down and Enter when several are running. Esc or Ctrl+C cancels. If a successful query finds no running sessions, setup uses `default`. If no Herdr installation is found, setup offers to install it for `default`. If an installed binary cannot report its sessions, setup reports the error; pass `--remote-session <name>` to select a session explicitly.
+
+The sidebar shows the default session as `workbox`, the SSH host without any `user@` prefix. Add `--label "Build machine"` to choose a different name. A machine profile targets one remote session; it does not combine every session on the host. Non-interactive commands use `default` unless `--remote-session` is supplied.
+
+To skip discovery and use a specific session, add `--remote-session`:
+
+```bash
+herdr machine add workbox --remote-session agents
+```
+
+Without `--label`, this machine shows as `workbox/agents`. If the default name is already taken, `machine add` asks you to pass `--label`.
+
+On Windows servers, setup also checks executables used by Herdr processes owned by the SSH user. It validates their capabilities before reuse, so a compatible running build can be used even when SSH's `PATH` points to an older installation.
+
+Herdr checks both the installed binary and the running server. It starts the requested background server before saving the profile. Compatible client and server versions do not have to match. Missing or incompatible installations go through an approval-based setup. When the running server needs replacement, setup asks before stopping it and its pane processes, then starts the compatible server. The default answer is No. If installation and replacement are both needed, one confirmation covers them. `machine add` does not use experimental live handoff. Cancelling or failing setup leaves the profile unsaved.
+
+Run `herdr` to open the UI. If a local client is already open, added and enabled machines normally appear within a second and connect in the background without changing your selection. An in-progress machine switch finishes before profile changes are applied. The remote server keeps running after setup exits.
+
+## Switch between machines
+
+Choose a machine or one of its workspaces in the sidebar. The selected machine receives your pane input and terminal size, and supplies the visible terminal content and graphics. Other connected machines keep updating their workspace information, agent states, and notifications without streaming their pane screens.
+
+Click the arrow beside any machine to collapse or expand its workspace list without switching away from your current workspace. This also works while that machine is reconnecting.
+
+For keyboard navigation, press `prefix+w`, then use the workspace navigation keys (Up/Down by default) to highlight workspaces across connected machines in sidebar order. Enter activates the highlighted workspace; Esc or the prefix key cancels without switching. Compact and expanded sidebars reveal the highlighted row, including under a collapsed machine. On desktop, navigation wraps at the ends; the mobile switcher stops at the first or last workspace. Disconnected machines are skipped.
+
+When highlighting a workspace on another machine, press Enter before using other keyboard actions. This prevents pane, tab, workspace, or custom-command shortcuts from acting on the current machine by mistake. Clicking cancels a remote desktop keyboard preview. Expanded sidebars respect each machine's collapsed worktree groups.
+
+Local opens immediately on startup without waiting for SSH connections. Selecting Local also cancels an unfinished remote switch without waiting for the remote machine to reply. If Local itself is reconnecting, your selection resumes when it is ready. Local accepts input once its fresh screen and terminal settings are ready. A stalled machine cannot hold up another machine's input. Multiple Herdr clients can also view different tabs on the same server independently; see [Client and server](/docs/concepts/#client-and-server) for shared-tab sizing.
+
+When a connection is lost, the last workspace and agent state remains visible but dimmed. That is cached information, not live state. Input and navigation into those cached panes stay disabled until a fresh connection and matching screen arrive. Reconnecting never takes selection away from the machine you are using.
+
+## Rename, disable, or remove
+
+Read profile IDs from the list rather than deriving them from labels or hostnames:
+
+```bash
+herdr machine list
+herdr machine rename <profile-id> --label "New name"
+herdr machine disable <profile-id>
+herdr machine enable <profile-id>
+herdr machine remove <profile-id>
+```
+
+For scripts, add `--json` to `machine list`.
+
+Renaming changes the displayed label without reconnecting. Disabling keeps the profile for later; removing forgets it. Both disconnect only that machine from the client and leave its remote sessions and agents running, even if the host is unreachable.
+
+Removing or disabling the machine you are viewing returns you to Local. If Local is unavailable, Herdr shows that and retries its connection instead of selecting a different remote machine. With enabled saved machines, the client can remain usable even if Local fails or restarts.
+
+## Connection problems
+
+- **Reconnecting:** Herdr retries automatically after a network interruption, sleep, or SSH failure. Repeated failures increase the delay up to two minutes; brief successful connections do not reset it. A connection must remain healthy for a minute before the next interruption gets a fast retry. SSH connections are checked for application-level activity and probed when quiet, so a broken connection does not stay Online indefinitely. Local detects native connection closure or failure instead of using remote health probes.
+- **Attention:** The target needs an action such as authentication, host-key approval, or a compatible server. Other machines remain usable. **`! auth`** means authentication failed; **`! error`** indicates another issue. Click the badge for the error and a CLI command. In a collapsed sidebar, either appears as `!`.
+- **Saved-machine file error:** An unreadable or invalid catalog leaves current connections unchanged. Herdr shows a notice and automatically retries reading it.
+
+When both installations support bridge idle cleanup, saved-machine connections to Linux and macOS also close their remote bridge after a minute without traffic in either direction. Sleep counts toward that deadline, which is checked when the host wakes. Quiet healthy connections exchange health checks; watching continuous output does not require typing. Cleanup leaves the remote Herdr server, sessions, and pane processes running. Older installations remain compatible without this optional cleanup.
+
+Background connections never answer prompts or install, update, restart, or hand off a server. For non-authentication Attention, run the standalone setup command shown by Herdr in an interactive terminal, for example:
+
+```bash
+herdr --remote workbox
+```
+
+Use your profile's target. If you chose a named session when adding it, include the optional `--session <name>` here too. Follow the requested setup prompts; open clients retry automatically. `machine reconnect` does not install or update Herdr. Do not stop a running server merely because its version differs from the client.
+
+If authentication fails, check ordinary SSH first. For a passphrase-protected key, load it with `ssh-add` before starting Herdr's non-interactive background connections.
+
+For Git authentication or SSH signing inside remote panes, enable `ForwardAgent yes` for the trusted host in your SSH config. Herdr does not enable forwarding for you. When a session starts with an agent, updated Linux and macOS servers give panes a stable agent address, so existing and new panes can use the forwarded agent after `--remote` or a saved machine reconnects. A working inherited agent or earlier connection keeps priority over later clients and temporary setup checks; if it disappears, another live attachment can supply the agent.
+
+This requires an updated remote server, not just an updated local client. Local sessions started without an agent leave `SSH_AUTH_SOCK` alone. Panes created before the server update, or before an agent was first supplied to the session, keep their original environment and need to be recreated once to inherit the stable address. Older compatible servers and connections without agent forwarding can still attach normally.
+
+## Settings and automation
+
+The UI uses the client's local theme, sidebar settings, and keybindings by default. Custom commands and plugins advertised by the selected server still run there. Herdr does not copy local command plugins, configuration, executables, or secrets onto SSH hosts. Missing remote commands fail visibly. Use the UI's `reload config` action after editing client settings; see [Configuration](/docs/configuration/#reload-config).
+
+Default agent rows show a `machine` token when multiple machines are present. Existing custom rows are preserved; add `machine` explicitly if you want that label in your layout. [Sidebar row layouts](/docs/configuration/#sidebar-row-layouts) also support conditional colors for machine labels.
+
+Workspace, tab, pane IDs, and agent names are scoped to one server. Two machines may both contain `w1:p1` or an agent named `reviewer`. Selecting a machine in the UI does not retarget CLI commands running in an existing pane: they still use that pane's inherited session and socket. For remote automation, use `herdr --machine <label-or-id> agent list`, then pass the same prefix when controlling those remote IDs. The CLI uses the saved profile's SSH target and session directly; it does not need an open TUI. Without `--machine`, existing session/socket routing is unchanged. See [CLI reference](/docs/cli-reference/#saved-ssh-machines) for supported commands, update requirements, and remote path rules.
+
+## Updates and saved data
+
+Saved profiles contain only an opaque ID, label, SSH target, explicit remote session, and enabled state. Herdr does not store passwords, private keys, agent tickets, or SSH control sockets in the catalog. Authentication stays with OpenSSH.
+
+Herdr separately remembers each machine's remote OS and resolved executable path so repeated `--machine` commands can skip discovery. Existing profiles learn missing information on first use. This cache is optional: missing, invalid, or unwritable cache files do not prevent commands from working. Commands still check live server compatibility. If a cached executable is missing or no longer supports API forwarding, Herdr rediscovers it during the initial read-only check; it never automatically repeats a command that may already have changed remote state.
+
+The client and server negotiate compatibility rather than requiring identical versions. Saved-machine connections additionally need the server's `surface_interest` and `health_check` capabilities. Older servers without those capabilities show Attention until explicitly updated, even if a standalone attach works. Other missing server methods disable only their corresponding actions.
+
+Updating a compatible client does not replace the running remote server or stop its agents. When you need new server-side behavior, update that server explicitly. Normal replacement asks before stopping the server and its pane processes.
+
+Live handoff is experimental and opt-in. For a supported server that needs replacement during standalone setup, you can explicitly add `--handoff` to `herdr --remote`; it is not needed for normal connections or authentication fixes. See [Update](/docs/install/#update) for restart and handoff choices, and [Session state and restore](/docs/session-state/) for what survives each operation.
@@ -0,0 +1,103 @@
+---
+title: How to work with Herdr
+description: Run Herdr locally, inside SSH, or through remote attach.
+---
+
+Run Herdr where the work lives. Attach from wherever you are.
+
+Herdr is a background session server plus one or more terminal clients. Panes keep running in the server. Clients attach, detach, and render the session.
+
+## Local work
+
+Start Herdr from the project directory:
+
+```bash
+herdr
+```
+
+Herdr starts or attaches to your local background session automatically. You do not manage sockets. Run shells, servers, tests, and agents normally inside panes.
+
+Detach the client with `ctrl+b q`. Your panes keep running.
+
+Reattach later:
+
+```bash
+herdr
+```
+
+If you want to end the session and stop its panes, stop the server:
+
+```bash
+herdr server stop
+```
+
+## Remote work through normal SSH
+
+SSH to the machine that has the code and credentials, then run Herdr there:
+
+```bash
+ssh you@server
+herdr
+```
+
+This works like a terminal multiplexer. Your shell is remote. The Herdr server is remote. The agents and panes run on the remote machine. Detach with `ctrl+b q`, disconnect, then SSH back and run `herdr` again.
+
+Use this path when you already live inside an SSH shell, when you are on a phone or tablet SSH client, or when you want the simplest setup.
+
+## Work from your phone
+
+Herdr works on your phone without a mobile app or web dashboard. Install any SSH client, connect to the machine where your agents run, and start Herdr there:
+
+```bash
+ssh you@server
+herdr
+```
+
+The same persistent Herdr session opens in your phone terminal. The TUI adapts to narrow screens, so you can inspect agents, switch workspaces, and check panes without leaving SSH.
+
+On iPhone, apps like [moshi](https://getmoshi.app/) work well.
+
+<div class="mobile-doc-shots">
+  <figure>
+    <img src="/assets/mobile-agent-session-v2.jpeg" alt="Herdr agent session over SSH on a phone" loading="lazy" />
+    <figcaption>agent session over SSH</figcaption>
+  </figure>
+  <figure>
+    <img src="/assets/mobile-switch-menu-v2.jpeg" alt="Herdr responsive switch menu on a phone" loading="lazy" />
+    <figcaption>responsive switch menu</figcaption>
+  </figure>
+</div>
+
+## Remote work from your local terminal
+
+Attach through SSH without opening a shell first:
+
+```bash
+herdr --remote workbox
+herdr --remote ssh://you@server:2222
+```
+
+The remote server keeps the panes running and sends their terminal content and session state over SSH. Your local Herdr draws the UI using your local theme and presentation settings.
+
+Use this path when you want the remote session to feel local. The client runs on your machine, so local desktop features such as image clipboard paste can be bridged to the remote server. If you SSH first and run `herdr` on the server, Herdr runs entirely on that server and cannot read your local desktop clipboard.
+
+For repeat targets, put the host in your SSH config:
+
+```text
+Host workbox
+  HostName server.example.com
+  User you
+  Port 2222
+```
+
+Then attach with:
+
+```bash
+herdr --remote workbox
+```
+
+## Which path to use
+
+Use `herdr` for local work. Use `ssh you@server` then `herdr` when you want Herdr to behave like tmux on that remote shell or when you are using a phone SSH client. Use `herdr --remote <host>` for a local UI attached to one remote session, including local clipboard image paste. To keep Local and several SSH machines in one window, save them with `herdr machine add <host> --label <label>`; see [Connecting machines](/docs/connecting-machines/).
+
+For remote bootstrap details, named remote sessions, custom binaries, and direct terminal attach, see [Persistence and remote access](/docs/persistence-remote/).
@@ -0,0 +1,82 @@
+---
+title: Herdr documentation
+description: Terminal workspace manager for AI coding agents.
+template: splash
+hero:
+  tagline: "Install, learn, and configure Herdr. Start on the path that matches you — no multiplexer experience required."
+  image:
+    file: ../../../public/assets/logo.svg
+  actions:
+    - text: Install Herdr
+      link: /docs/install/
+    - text: Quick start
+      link: /docs/quick-start/
+      variant: secondary
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+## Pick your path
+
+<CardGrid>
+  <Card title="New to terminal multiplexers?">
+    You don't need to learn shortcuts to start. Herdr is mouse-first: click panes, drag borders, split and switch from right-click menus.
+
+    [Quick start →](/docs/quick-start/)
+  </Card>
+  <Card title="Coming from tmux or zellij?">
+    You already know the model. The prefix is `ctrl+b`, panes persist, detach and reattach work the way you expect.
+
+    [Concepts →](/docs/concepts/) · [Keybindings →](/docs/configuration/#keybindings)
+  </Card>
+</CardGrid>
+
+## Or let your agent introduce you
+
+If you already run an AI coding agent, let it handle the onboarding. Paste this prompt:
+
+```text
+Help me understand and set up Herdr. Read https://herdr.dev/agent-guide.md first, then walk me through it step by step.
+```
+
+The guide covers Herdr's concepts, setup, configuration, and common fixes, so your agent can answer from the docs instead of improvising.
+
+## Core guides
+
+<CardGrid>
+  <Card title="Agents">
+    See supported agents, detection behavior, integrations, custom labels, and direct attach.
+
+    [Understand agents →](/docs/agents/)
+  </Card>
+  <Card title="Connecting machines">
+    Keep Local and saved SSH machines in one window, with a combined agent list and independent reconnects.
+
+    [Connect your machines →](/docs/connecting-machines/)
+  </Card>
+  <Card title="Session state">
+    Understand detach, restart restore, pane history replay, native agent resume, and live handoff.
+
+    [Compare state paths →](/docs/session-state/)
+  </Card>
+  <Card title="Configuration">
+    Configure keybindings, themes, sidebar behavior, notifications, scrollback, and advanced options.
+
+    [Configure Herdr →](/docs/configuration/)
+  </Card>
+  <Card title="API">
+    Control Herdr from scripts, tools, and agents through the CLI and local socket API.
+
+    [Read the API guide →](/docs/socket-api/)
+  </Card>
+  <Card title="Plugins">
+    Author local executable workflow plugins with manifest actions and event hooks.
+
+    [Write a plugin →](/docs/plugins/)
+  </Card>
+  <Card title="Marketplace">
+    Share plugins from GitHub today and tag your repo to be listed when the marketplace launches.
+
+    [Publish a plugin →](/docs/marketplace/)
+  </Card>
+</CardGrid>
@@ -0,0 +1,158 @@
+---
+title: Install Herdr
+description: Install, update, and verify Herdr on Linux, macOS, and Windows.
+---
+
+Herdr publishes stable-channel binaries for Linux, macOS, and Windows. Windows is generally available, with documented platform-specific limitations and ongoing fixes.
+
+## Install
+
+On Linux or macOS, run:
+
+```bash
+curl -fsSL https://herdr.dev/install.sh | sh
+```
+
+On Windows, run:
+
+```powershell
+powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
+```
+
+If endpoint security blocks that fileless PowerShell command, open Command Prompt and run:
+
+```cmd
+curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del install.cmd
+```
+
+The installer downloads the release binary for your platform and places it on your PATH. New direct installs use the stable update channel. Existing Windows preview installs stay on preview until you switch them with `herdr channel set stable`. On Windows, PATH points to the active versioned release directory; the installer also updates the `current` and stable `bin` compatibility aliases, so updates do not need to overwrite a running `herdr.exe`.
+
+## Install with Homebrew
+
+If you already use Homebrew:
+
+```bash
+brew install herdr
+```
+
+## Install with mise
+
+If you already use mise:
+
+```bash
+mise use -g herdr
+```
+
+If mise reports `herdr not found in mise tool registry`, update mise and retry. Older mise versions predate the Herdr registry entry; `mise use -g github:herdrdev/herdr` works as a temporary fallback.
+
+## Install with Nix
+
+If you already use Nix, Herdr provides a flake that builds Herdr from source:
+
+```bash
+nix run github:herdrdev/herdr/v0.x.y
+nix build github:herdrdev/herdr/v0.x.y
+nix profile install github:herdrdev/herdr/v0.x.y
+```
+
+Replace `v0.x.y` with the latest release tag. You can omit the tag to track `master`, but release tags are recommended for normal installs.
+
+The flake also exposes a development shell:
+
+```bash
+nix develop github:herdrdev/herdr
+```
+
+Use the same Nix workflow to update Herdr. For a profile install, list your profile entries and upgrade the Herdr entry:
+
+```bash
+nix profile list
+nix profile upgrade <index-or-name>
+```
+
+If Herdr is an input in your own flake, update that input and rebuild your system, Home Manager, or development environment:
+
+```bash
+nix flake update herdr
+```
+
+## Download manually
+
+You can also download a binary from [GitHub releases](https://github.com/herdrdev/herdr/releases).
+
+Choose the asset that matches your system:
+
+| System | Asset |
+| --- | --- |
+| Linux x86_64 | `herdr-linux-x86_64` |
+| Linux aarch64 | `herdr-linux-aarch64` |
+| macOS Intel | `herdr-macos-x86_64` |
+| macOS Apple silicon | `herdr-macos-aarch64` |
+| Windows x86_64 | `herdr-windows-x86_64.zip` |
+
+On Linux or macOS, make it executable and move it somewhere on your PATH.
+
+```bash
+chmod +x herdr-linux-x86_64
+mv herdr-linux-x86_64 ~/.local/bin/herdr
+```
+
+### Windows archive
+
+Stable releases and preview prereleases both include `herdr-windows-x86_64.zip`. The archive contains `herdr.exe` and its app-local ConPTY runtime. Keep the extracted directory together; do not copy only `herdr.exe`.
+
+## Verify
+
+Start Herdr:
+
+```bash
+herdr
+```
+
+If your shell cannot find `herdr`, restart the terminal or check that the install directory is on your PATH.
+
+## Update
+
+Herdr checks for new releases and notifies you in the app. You can update manually:
+
+```bash
+herdr update
+```
+
+Use `herdr update` only for installs managed by Herdr's own installer. Update Homebrew, mise, and Nix installs through those package managers instead.
+
+Direct installs on Linux, macOS, and Windows use the stable update channel by default. To opt into preview builds from `master`, set the channel:
+
+```bash
+herdr channel set preview
+```
+
+Switch a direct install back to stable the same way:
+
+```bash
+herdr channel set stable
+```
+
+For direct installs, changing channels checks the selected channel and installs its latest binary. If that update fails, run `herdr update` to retry from the configured channel.
+
+Preview builds are regularly published GitHub prereleases from the current development branch. They are useful when you want fixes before the next stable release, but they can regress. Homebrew, mise, and Nix installs do not use the preview channel.
+
+Stable is the recommended channel for normal Windows use. Preview receives fixes sooner but can regress, so opt in only when you want that tradeoff. Existing Windows preview installs remain on preview until you switch them explicitly. If an older preview build rejects `herdr channel set stable`, run `herdr update` once on preview, then retry the channel switch.
+
+By default, `herdr update` installs the new binary and leaves endpoint-generation-1 servers and their pane processes running. Start Herdr again to reconnect with the updated client. Client-only changes work immediately. A new server-side action stays unavailable until that server is updated and restarted; the client shows a notice instead of disconnecting. Servers from before endpoint generation 1 need one final stop during update.
+
+When it finishes, `herdr update` lists any running server still on the old version with the command that restarts it, and your saved SSH machines, which run their own Herdr. Run `herdr update` on each machine to update it too.
+
+To opt into experimental live server handoff for supported running sessions, run:
+
+```bash
+herdr update --handoff
+```
+
+When both servers support agent-status transfer, live handoff preserves hook-reported agent status until the next report arrives. Handoff from an older server can temporarily show a running agent as idle.
+
+Live handoff does not apply to Homebrew, mise, or Nix package-manager updates. For those installs, update with the package manager, then run Herdr again to reconnect with the updated client. The compatible old server keeps running. Restart it later with `herdr server stop` or `herdr session stop <name>` only when you want server-side changes from the new release.
+
+## Requirements
+
+Stable-channel binaries are available for Linux, macOS, and Windows x86_64. See [Windows support](/docs/windows-beta/) for supported workflows and known limitations. Windows ARM64 runs the x86_64 build under Windows emulation.
@@ -0,0 +1,372 @@
+---
+title: Integrations
+description: Install Herdr integrations for Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, Devin CLI, Droid, Kimi Code CLI, OpenCode, Kilo Code CLI, Hermes Agent, Qoder CLI, Qwen Code, Letta Code, Cursor Agent CLI, MastraCode, Antigravity CLI, and Grok CLI.
+---
+
+Herdr detects the agents it supports automatically. Install an agent's integration so Herdr can resume the same session after a server restart. Some integrations also report the agent's state directly. See [Agents](/docs/agents/) for which agents Herdr supports and which support Herdr themselves.
+
+## Install integrations
+
+Open settings inside Herdr and use the integrations tab to install recommended integrations for agents found on your `PATH`, or run commands manually:
+
+```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 qwen
+herdr integration install letta
+herdr integration install cursor
+herdr integration install mastracode
+herdr integration install antigravity-cli
+herdr integration install grok
+```
+
+## Uninstall integrations
+
+```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 qwen
+herdr integration uninstall letta
+herdr integration uninstall cursor
+herdr integration uninstall mastracode
+herdr integration uninstall antigravity-cli
+herdr integration uninstall grok
+```
+
+Herdr saves integration configs atomically on Linux/macOS and for new files; existing Windows files keep their permissions through a backup-first, in-place update. If Windows reports a backup, close the agent and inspect the config before retrying: discard—not restore—an unfinished `.herdr-backup.pending` only after verifying the config, or restore completed `.herdr-backup` contents into the existing file if needed (if missing, establish its intended permissions first), then verify the config and remove the backup.
+
+## How Herdr uses integrations
+
+Every integration tells Herdr which session the agent is in, so Herdr can resume it after a server restart. Turn this off with `[session] resume_agents_on_restore = false`.
+
+The Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, and MastraCode integrations also report the agent's state. While they report, Herdr uses them instead of reading the screen. Codex reports turn state when run with `--no-daemon`; screen detection still handles its visible blockers. Other integrations leave state to screen detection.
+
+Native session restore requires current Herdr integrations: Pi integration version `2`, OMP version `3`, Claude Code version `6`, Codex version `5`, GitHub Copilot CLI version `2`, Devin CLI version `2`, Droid version `2`, Kimi Code CLI version `3`, Qoder CLI version `2`, Qwen Code version `1`, Letta Code version `1`, Cursor Agent CLI version `1`, Grok CLI version `2`, OpenCode version `5`, Kilo Code CLI version `1`, Hermes Agent version `5`, MastraCode version `1`, or Antigravity CLI version `1`. Check installed versions with `herdr integration status`.
+
+## Integrate your own agent
+
+If you build a coding agent, you can report its state and resume command to Herdr from your own code, without adding native support to Herdr. See [Add Herdr support to your agent](/docs/add-herdr-support/).
+
+## Pi
+
+Install the Pi integration:
+
+```bash
+herdr integration install pi
+```
+
+Herdr writes the bundled extension to:
+
+```text
+~/.pi/agent/extensions/herdr-agent-state.ts
+```
+
+If `PI_CODING_AGENT_DIR` is set, Herdr writes to `$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts` instead. Herdr creates the extensions directory when the Pi agent directory already exists. Uninstall removes only that extension file.
+
+## OMP
+
+Install the OMP integration:
+
+```bash
+herdr integration install omp
+```
+
+Herdr writes the bundled extension to:
+
+```text
+~/.omp/agent/extensions/herdr-omp-agent-state.ts
+```
+
+Herdr uses `PI_CODING_AGENT_DIR` as the complete agent directory when set. Otherwise, it uses `$HOME/$PI_CONFIG_DIR/agent` when `PI_CONFIG_DIR` is set, falling back to `~/.omp/agent`. If Pi and OMP resolve to the same extension directory, Herdr refuses the OMP install so the OMP extension cannot be loaded by Pi. Configure separate agent directories before installing both integrations. Herdr creates the extensions directory when the resolved OMP agent directory already exists. Uninstall removes only that extension file.
+
+The OMP integration reports `omp` as the agent label, lifecycle state, and native session identity through Herdr's socket API. It does not require native process detection for the `omp` executable, and Herdr can resume an OMP pane with `omp --resume=<session>` after a server restart.
+
+## Claude Code
+
+Install the Claude Code hook:
+
+```bash
+herdr integration install claude
+```
+
+The hook reports Claude Code session identity to the local Herdr socket on session start. Claude Code state comes from Herdr's screen manifest detection.
+
+Claude integration v10 matches only the documented `SessionStart` sources: `startup`, `resume`, `clear`, `compact`, and `fork`. This prevents Grok's `new` and `load` events from launching the imported Herdr Claude hook, without disabling unrelated Claude-compatible hooks. Reinstall the Claude integration after upgrading to migrate the previous wildcard matcher. New Claude source values require an integration update.
+
+Herdr uses `~/.claude` by default, or `CLAUDE_CONFIG_DIR` when set. The Claude config directory must already exist. Install writes `hooks/herdr-agent-state.sh` and updates `settings.json` with Herdr hook entries. Uninstall removes the matching hook entries and deletes the hook script.
+
+## Codex
+
+Install the Codex hook:
+
+```bash
+herdr integration install codex
+```
+
+When Codex runs with `--no-daemon`, the hook reports session identity and turn start/stop state through Herdr's local socket API. Screen detection still handles visible blockers and fills gaps when hooks are unavailable. A shared Codex daemon can route hooks to the wrong pane, so use `--no-daemon` for reliable reports; disabling daemon auto-start alone does not stop an existing daemon.
+
+Herdr uses `~/.codex` by default, or `CODEX_HOME` when set. The Codex config directory must already exist. Install writes `herdr-agent-state.sh`, updates `hooks.json`, and ensures `[features] hooks = true` in `config.toml`. It also removes the deprecated top-level `codex_hooks` flag when present. Uninstall removes Herdr entries from `hooks.json` and deletes the hook script, but leaves `config.toml` unchanged.
+
+## GitHub Copilot CLI
+
+Install the GitHub Copilot CLI hook:
+
+```bash
+herdr integration install copilot
+```
+
+The Copilot hook reports session identity through the same local socket API used by other integrations. Copilot state comes from Herdr's screen manifest detection.
+
+Herdr uses `~/.copilot` by default, or `COPILOT_HOME` when set. The Copilot config directory must already exist. Install writes `hooks/herdr-agent-state.sh` and updates `settings.json` with a `SessionStart` hook entry. Uninstall removes Herdr entries from `settings.json` and deletes the hook script.
+
+After Copilot emits a session-bearing event, Herdr can use the reported session id to resume the pane with `copilot --resume=<id>`.
+
+## Devin CLI
+
+Install the Devin CLI hook:
+
+```bash
+herdr integration install devin
+```
+
+The hook reports native session identity from Devin session, prompt, tool-use, permission, and stop events. Devin state still comes from Herdr's screen manifest and OSC detection because Devin hooks do not emit a reliable state transition after every permission cancellation or user interrupt.
+
+Herdr uses `$XDG_CONFIG_HOME/devin` when `XDG_CONFIG_HOME` is set. Otherwise, it uses `~/.config/devin` on Linux and macOS or `%APPDATA%\devin` on Windows. The Devin config directory must already exist. Install writes `herdr-agent-state.sh` on Unix or `herdr-agent-state.ps1` on Windows and updates `config.json` with Herdr hook entries. The hook refreshes the session reference while Devin runs. Uninstall removes Herdr entries from `config.json` and deletes the hook script.
+
+Herdr resumes stored Devin sessions with `devin --resume <id>`. Native screen manifest detection remains the state authority whether or not the hook is installed.
+
+## Kimi Code CLI
+
+Install the Kimi Code CLI hook:
+
+```bash
+herdr integration install kimi
+```
+
+The hook reports Kimi session identity and lifecycle state to Herdr for native restore and authoritative `idle`, `working`, and `blocked` status. It requires Kimi Code CLI `0.14.0` or newer.
+
+Herdr uses `~/.kimi-code` by default, or `KIMI_CODE_HOME` when set. The Kimi Code config directory must already exist. Install writes `hooks/herdr-agent-state.sh` and appends Herdr-managed `[[hooks]]` entries to `config.toml`. Uninstall removes the Herdr-managed config block and deletes the hook script.
+
+Herdr resumes stored Kimi sessions with `kimi --session <id>`.
+
+## Droid
+
+Install the Droid hook:
+
+```bash
+herdr integration install droid
+```
+
+The Droid hook reports session identity through the same local socket API used by other integrations. Lifecycle state still comes from Herdr's screen manifest detection because Droid hooks do not cover every lifecycle transition.
+
+Herdr uses `~/.factory` for Droid hooks. The Factory config directory must already exist. Install writes `hooks/herdr-agent-state.sh`, updates `settings.json` with a Herdr `SessionStart` hook entry, and removes older Herdr Droid hook entries from `hooks.json` if present. Uninstall removes Herdr entries from both config files and deletes the hook script.
+
+After Droid emits a session start event, Herdr can use the reported session id to resume the pane with `droid --resume <id>`.
+
+## OpenCode
+
+Install the OpenCode plugin:
+
+```bash
+herdr integration install opencode
+```
+
+The integration supports OpenCode V1 `1.18.29` or later and OpenCode V2 (tested with beta `19242`). The OpenCode config directory must already exist. Herdr installs the server entrypoint at `~/.config/opencode/plugins/herdr-agent-state.js`, the shared TUI plugin at `herdr-tui-session.js`, and a V2 TUI entrypoint at `herdr-opencode/tui.js` in that config directory.
+
+Install registers the V1 TUI plugin in `tui.jsonc` and the V2 TUI plugin in `cli.json`, preserving other preferences and plugins. An existing V1 registration in `tui.json` also counts as installed and is reused without creating `tui.jsonc`. Uninstall removes the Herdr registration from both TUI config files while keeping the files and other preferences. If OpenCode still has V1 TUI preferences to import (`tui.json` or `kv.json`), Herdr defers registration so the first-start migration can run; start `opencode2` once and reinstall the integration afterward. Otherwise Herdr creates `cli.json` with the plugin registration. Restart the OpenCode TUI after installation. Uninstall removes the managed plugin files and their configuration entries.
+
+V2 lifecycle reporting runs in the pane-local TUI, which associates events with its selected root session even when multiple panes share one OpenCode server. Completion and interruption clear the working state; pending permission requests, pending forms, and failed executions keep the pane blocked. V2 Mini and headless clients do not run the TUI plugin and therefore do not provide this lifecycle reporting.
+
+V1 TUI reporting follows the pane's selected session and its descendants. The pane stays working while any of them is busy or retrying, and blocked while any has a pending permission or question. Attaching loads existing activity; cancelled tool requests do not become blockers again after reconnecting. Browsing a subagent keeps the original session family, while directly attaching to a child tracks that child's subtree rather than its siblings.
+
+Local V1 `opencode run` and `opencode --mini` retain their legacy server hooks; this change does not add pane-local lifecycle reporting to Mini/headless clients. After updating the integration, restart shared OpenCode servers as well as their TUIs so the old server reporter cannot overwrite pane-local state.
+
+The plugin reports lifecycle state and session identity while OpenCode runs inside a Herdr pane. After OpenCode emits a session-bearing event, Herdr can use the reported session id to resume the pane with `opencode --session <id>`. Native screen manifest detection remains available when the plugin is not installed.
+
+## Kilo Code CLI
+
+Install the Kilo Code CLI plugin:
+
+```bash
+herdr integration install kilo
+```
+
+Herdr writes the plugin to `~/.config/kilo/plugin/herdr-agent-state.js`. The Kilo config directory must already exist. Uninstall removes only that plugin file.
+
+The plugin reports lifecycle state and session identity while Kilo runs inside a Herdr pane. After Kilo emits a session-bearing event, Herdr can use the reported session id to resume the pane with `kilo --session <id>`. Native screen manifest detection remains available when the plugin is not installed.
+
+## Hermes Agent
+
+Install the Hermes Agent plugin:
+
+```bash
+herdr integration install hermes
+```
+
+Herdr writes `plugins/herdr-agent-state/` under the Hermes home directory and enables `herdr-agent-state` in its `config.yaml`. `HERMES_HOME` defaults to `~/.hermes` on Unix and `%LOCALAPPDATA%\hermes` on Windows. The Hermes config directory must already exist. Restart Hermes after installing so the plugin loads. Uninstall removes the plugin directory and removes `herdr-agent-state` from `plugins.enabled`.
+
+The plugin reports the resumable session id while Hermes runs inside a Herdr pane. Herdr uses screen manifest detection for `working`, `idle`, and `blocked`, and can use the reported session id to resume the pane with `hermes --resume <id>`.
+
+## Qoder CLI
+
+Install the Qoder CLI hook:
+
+```bash
+herdr integration install qodercli
+```
+
+The hook reports Qoder CLI session identity to Herdr for native restore. Lifecycle state still comes from Herdr's screen manifest detection because Qoder hooks do not cover every lifecycle transition.
+
+Herdr uses `~/.qoder` by default, or `QODER_CONFIG_DIR` when set. The Qoder config directory must already exist. Install writes `hooks/herdr-agent-state.sh` and updates `settings.json` with Herdr hook entries. Uninstall removes the matching hook entries and deletes the hook script.
+
+Herdr resumes stored Qoder CLI sessions with `qodercli --resume <id>`.
+
+Native screen manifest detection remains available when the hook is not installed.
+
+## Qwen Code
+
+Install the Qwen Code hook:
+
+```bash
+herdr integration install qwen
+```
+
+The `SessionStart` hook reports only Qwen Code's session identity for native restore. Lifecycle state remains under Herdr's screen manifest detection.
+
+Herdr uses `~/.qwen` by default, or `QWEN_HOME` when set. The Qwen config directory must already exist. Install writes `hooks/herdr-agent-session.sh` (`hooks/herdr-agent-session.ps1` on Windows) and adds a Herdr entry to `settings.json`. Uninstall removes only the matching entry and managed script.
+
+Herdr resumes stored Qwen Code sessions with `qwen --resume <id>`.
+
+## Letta Code
+
+Letta Code integration installation is experimental and CLI-only. It is not listed in the Settings integration screen or the JSON integration API. `herdr integration status` reports it as `letta (experimental)`. Agent detection and `herdr agent start --kind letta` are supported independently of this installation restriction.
+
+Install the Letta Code hook:
+
+```bash
+herdr integration install letta
+```
+
+The quiet `SessionStart` hook reports the conversation ID for native restore. Letta Code state still comes from Herdr's screen manifest detection.
+
+Herdr uses `~/.letta`. The config directory must already exist. Install writes `hooks/herdr-agent-session.sh` (`hooks/herdr-agent-session.ps1` on Windows) and adds a Herdr entry to `settings.json`. Uninstall removes only the matching entry and managed script.
+
+Herdr resumes named conversations with `letta --conversation <id>`. It records the default conversation as `default:<agent-id>` and resumes it with `letta --conversation default --agent <agent-id>`.
+
+## Cursor Agent CLI
+
+Install the Cursor Agent CLI hook:
+
+```bash
+herdr integration install cursor
+```
+
+The hook reports session identity through Cursor's `sessionStart` hook while Cursor Agent CLI runs inside a Herdr pane. Cursor state comes from Herdr's screen manifest detection.
+
+Herdr uses `~/.cursor` by default, or `CURSOR_CONFIG_DIR` when set. The Cursor config directory must already exist. Install writes `herdr-agent-state.sh` (`herdr-agent-state.ps1` on Windows) and adds a Herdr `sessionStart` entry to `hooks.json`. Uninstall removes the matching hook entry and deletes the hook script.
+
+After Cursor emits a session start event, Herdr can use the reported session id to resume the pane with `cursor-agent --resume <id>`. The `cursor-agent` command must be on `PATH` when Herdr restores the pane; Herdr does not launch the generic `agent` command.
+
+## MastraCode
+
+Install the MastraCode hook:
+
+```bash
+herdr integration install mastracode
+```
+
+The hook reports MastraCode lifecycle state and thread identity to Herdr for authoritative `idle`, `working`, and `blocked` status and native restore. MastraCode has no screen manifest fallback; state comes from the hook while MastraCode runs inside a Herdr pane.
+
+Herdr uses `~/.mastracode`. Install writes `hooks/herdr-agent-state.sh` (`hooks/herdr-agent-state.ps1` on Windows) and adds Herdr command entries to `hooks.json`, creating the directory when missing. Uninstall removes the matching hook entries and deletes the hook script.
+
+Herdr resumes stored MastraCode threads with `mastracode --thread <id>`.
+
+## Antigravity CLI
+
+Install the Antigravity CLI hook:
+
+```bash
+herdr integration install antigravity-cli
+```
+
+Herdr uses `~/.gemini/config/` by default, or `ANTIGRAVITY_CLI_CONFIG_DIR` when set. This is the directory Antigravity CLI reads global customizations from, and it must already exist. Install writes `hooks/herdr-agent-state.sh` (or `herdr-agent-state.ps1` on Windows) and adds a Herdr-owned `herdr` block to `hooks.json`. Antigravity CLI keys `hooks.json` by hook name, so install rewrites only that block and leaves other named hooks untouched. Uninstall removes the `herdr` block and deletes the hook script.
+
+This session-only integration reports the pane's current conversation, but not agent state. Herdr keeps deriving working, idle, and blocked from what Antigravity CLI draws on screen.
+
+The hook runs on `PreInvocation`, so Herdr learns the conversation once the first prompt is sent. From then on Herdr can resume the pane with `agy --conversation <id>` after a Herdr server restart.
+
+## Grok CLI
+
+Install the Grok CLI hook:
+
+```bash
+herdr integration install grok
+```
+
+The hook reports session identity through Grok's `SessionStart` hook while Grok CLI runs inside a Herdr pane. Grok state comes from Herdr's screen manifest detection.
+
+Herdr uses `~/.grok` by default, or `GROK_HOME` when set. The Grok config directory must already exist. Grok merges every `hooks/*.json` file in that directory, so install writes a self-contained `hooks/herdr.json` with the Herdr `SessionStart` entry next to `hooks/herdr-agent-state.sh` (`hooks/herdr-agent-state.ps1` on Windows), and never edits other hook files. Uninstall removes exactly those two Herdr-owned files.
+
+After Grok emits a session start event, Herdr can use the reported session id to resume the pane with `grok --resume <id>`.
+
+## Custom status labels
+
+Integrations report lifecycle state as semantic state only. For example, report an agent as `working` without adding display fields to the lifecycle report.
+
+```bash
+herdr pane report-agent w1:p1 \
+  --source custom:docs \
+  --agent docs-bot \
+  --state working
+```
+
+User hooks that run next to a Herdr-managed integration should use metadata instead of `report-agent`. Metadata changes presentation without taking over the integration's `idle`, `working`, `blocked`, or session restore authority. `--agent` and `--applies-to-source` guard only presentation fields (`--title`, `--display-agent`, and `--state-label`). Token patches always apply; their reporter owns clearing or TTL refresh. `--display-agent` changes the visible name.
+
+```bash
+herdr pane report-metadata "$HERDR_PANE_ID" \
+  --source user:claude-title \
+  --agent claude \
+  --title "Refactor auth middleware" \
+  --display-agent "Claude: auth" \
+  --token summary="refactor auth" \
+  --state-label working="refactoring auth" \
+  --ttl-ms 3600000
+```
+
+Tokens and state labels are visual-only. Waits, notifications, and workspace rollups still use the semantic state.
+
+## Debug integration state
+
+List known agents:
+
+```bash
+herdr agent list
+```
+
+Read a pane when you need to verify what Herdr can see:
+
+```bash
+herdr pane read w1:p1 --source recent --lines 50
+```
+
+If integration state looks wrong, first confirm the agent is running inside Herdr and that the relevant hook or plugin was installed for the same user account.
@@ -0,0 +1,114 @@
+---
+title: エージェントに Herdr 対応を追加する
+description: Herdr にネイティブサポートを追加せずに、自分のコードからコーディングエージェントの状態と resume コマンドを Herdr に報告します。
+---
+
+コーディングエージェントを開発しているなら、自分のコードだけでそのエージェントを Herdr の第一級の存在にできます。Herdr へのプルリクエストも、Herdr のリリースを待つ必要もありません。
+
+エージェントが Herdr に報告すると、ユーザーは次のものを得られます:
+
+- サイドバーと `herdr agent list` に表示されるエージェント名と `idle`、`working`、`blocked` の状態
+- 完了したときや判断が必要になったときの通知
+- `herdr agent wait` など、エージェントの状態を待つ自動化
+- Herdr サーバーの再起動後、同じペインで同じセッションが戻ること
+
+ベンダーがインテグレーションを提供していないエージェントについては、Herdr がインテグレーションを管理します。エージェントのメンテナーが自分でインテグレーションを持てば、自分のリリーススケジュールで修正できます。
+
+## 仕組み
+
+Herdr ペイン内のすべてのプロセスは、次の環境変数を継承します:
+
+| 変数 | 意味 |
+| --- | --- |
+| `HERDR_ENV` | Herdr 内では `1` |
+| `HERDR_PANE_ID` | エージェントが動いているペイン |
+| `HERDR_BIN_PATH` | このペインを管理する Herdr バイナリ |
+| `HERDR_SOCKET_PATH` | Herdr の API ソケット |
+
+エージェントは `"$HERDR_BIN_PATH"` を通じて 3 種類の報告をします:
+
+1. **状態。** `idle`、`working`、`blocked` が変わるたびに報告します。
+2. **resume コマンド。** 現在のセッションを開き直すコマンドを報告します。
+3. **解放。** エージェントの終了時にペインを解放します。
+
+`HERDR_ENV=1` で他の変数も設定されているときだけ報告してください。Herdr の外では、インテグレーションは何もしないようにします。
+
+## 状態を報告する
+
+```bash
+"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
+  --source my-agent \
+  --agent my-agent \
+  --state working \
+  --seq 1
+```
+
+- ターンの開始時に `working`、入力を受け付けられるときに `idle`、ユーザーの判断が必要なときに `blocked` を報告します。ブロックの理由は `--message` で説明できます。
+- `--agent` はユーザーに表示される名前です。Herdr がすでに対応しているエージェントの名前ではなく、自分のエージェントの名前を使ってください。
+- `--source` はインテグレーションを識別します。固定かつ一意にしてください。`herdr:` で始めないでください。この接頭辞は Herdr 自身のインテグレーションが使います。
+- `--seq` は省略できますが、付けることを推奨します。source からの報告ごとに増加する必要があり、エージェントのセッションや再起動をまたいでも増加し続ける必要があります。タイムスタンプが適しています。Herdr は最後に受け付けた番号より大きくない報告を無視するので、遅れて届いた報告や順不同の報告が新しい状態を上書きすることはありません。
+
+タイトルやカスタムのステータス文言など、状態を変えずにエージェントの見た目を変えるには、[カスタムステータスラベル](/ja/docs/integrations/#カスタムステータスラベル)を参照してください。
+
+## resume コマンドを報告する
+
+現在のセッションを再開するコマンドを `--` の後に置きます。モデルや権限モードなど、そのセッションに必要なオプションも含めると、再開したセッションが同じように動きます:
+
+```bash
+"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
+  --source my-agent \
+  --agent my-agent \
+  --state idle \
+  --seq 2 \
+  --agent-session-id "$SESSION_ID" \
+  -- my-agent --resume "$SESSION_ID" --model my-model
+```
+
+コマンドはどの状態報告に付けてもかまいません。セッションだけが変わったときは `pane report-agent-session` で送れます。エージェントがセッションを切り替えるたびに、もう一度報告してください。
+
+Herdr サーバーの再起動後、Herdr は同じディレクトリでペインを開き、そこでそのコマンドを実行します。コマンドは次のルールに従う必要があります:
+
+- 最初の語は、`my-agent` のようにユーザーの `PATH` 上にある単純なコマンド名にします。パスは使えません。
+- どの引数にもアポストロフィや制御文字を含めません。
+- 引数は最大 64 個、合計 8 KiB までです。
+- 先に source がペインを保持している必要があります。コマンドより前か同時に、`report-agent` で状態を報告してください。そうしないと Herdr は `resume_not_accepted` を返します。
+
+最初の 3 つのルールに違反するコマンドは、Herdr が `invalid_resume_argv` で拒否し、その報告は適用されません。ユーザーは `[session] resume_agents_on_restore = false` で resume を無効にできます。
+
+## 終了時に解放する
+
+```bash
+"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \
+  --source my-agent \
+  --agent my-agent \
+  --seq 3
+```
+
+解放すると、エージェントの名前、状態、resume コマンドがすぐにペインから消えます。解放するのはユーザーが実際に終了したときだけにしてください。同じプロセス内でセッションを別のセッションに置き換える場合は、解放せずに新しいセッションを報告します。
+
+エージェントが解放せずに終了した場合、Herdr はペインがアイドルなシェルプロンプトに戻ったことに気づき、エージェントと resume コマンドを消去します。通常は 1〜2 秒かかります。これは安全網であり、解放の代わりにはなりません。
+
+## エージェントの邪魔をしない
+
+- Herdr のせいでエージェントを遅くしないでください。報告はバックグラウンドか短いタイムアウトで送り、失敗は無視します。
+- 最新の状態だけを送ります。報告の送信中に複数の変化がたまったら、古いものは捨てます。
+- resume コマンドには Herdr 0.9.2 以降が必要です。古いバージョンはこれを無視するので、状態の報告と解放はそのまま動きます。
+
+## ソケットを直接使う
+
+`HERDR_BIN_PATH` と CLI は Windows を含めて移植性のある選択肢です。エージェントに直接の IPC が必要な場合は、[Socket API](/ja/docs/socket-api/) に記載された同等の `pane.report_agent`、`pane.report_agent_session`、`pane.release_agent` リクエストを送信します。resume コマンドは `resume_argv` 配列に入れます。
+
+## インテグレーションを確認する
+
+Herdr のペインでエージェントを起動し、Herdr から見える内容を確認します:
+
+```bash
+herdr pane get "$HERDR_PANE_ID"
+herdr agent list
+```
+
+普段のセッションに影響を与えずに復元をテストするには、別の名前付きセッションを使います:
+
+1. `herdr --session my-agent-test` を起動し、ペインでエージェントを実行します。
+2. `herdr session stop my-agent-test` でそのセッションを停止します。
+3. `herdr --session my-agent-test` をもう一度起動します。ペインで resume コマンドが実行され、エージェントが再び報告するはずです。
@@ -0,0 +1,127 @@
+---
+title: エージェント自動化
+description: Herdr のレイアウト、ペイン、エージェントの各プリミティブを使い、スクリプトや別のエージェントからコーディングエージェントを連携させます。
+---
+
+Herdr はコーディングエージェントの自動化レイヤーとして使えます。スクリプトから制御することも、ひとつのエージェントから別のエージェントへ作業を渡し、状態を確認して結果を集めることもできます。重要なのは、目的に合うプリミティブを選ぶことです。
+
+## 3 つのプリミティブ
+
+| プリミティブ | 責務 |
+| --- | --- |
+| レイアウト（`workspace`、`tab`、ペイン構成） | ターミナルの場所を作成し、整理する。 |
+| ペイン | 生のターミナルを制御する。コマンド実行、入力送信、出力読み取り、出力待機を行う。 |
+| エージェント | 認識済みコーディングエージェントを、名前またはペインとライフサイクル状態に基づいて制御する。 |
+
+ペインは、エージェントが入っていなくても存在します。エージェントは、ペイン内で現在実行されていると Herdr が認識したプロセスです。そのため `agent start` には既存のシェルペインが必要で、レイアウトの作成、分割、移動は行いません。
+
+ワークスペースを作成すると最初のタブとルートペインも作られ、タブを作成するとそのルートペインも作られます。最初のプロセスには返されたペイン ID を使い、そのレイアウトに別のターミナルが必要なときだけ分割します。
+
+作成コマンドは JSON を出力します。ID を推測せず、レスポンスから取得してください:
+
+```bash
+created=$(herdr workspace create --cwd ~/project --label api --no-focus)
+pane_id=$(printf '%s\n' "$created" | jq -r '.result.root_pane.pane_id')
+
+split=$(herdr pane split "$pane_id" --direction right --no-focus)
+review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
+```
+
+`workspace create` は `.result.workspace`、`.result.tab`、`.result.root_pane` を返します。`tab create` は `.result.tab` と `.result.root_pane` を返し、`pane split` は新しいペインを `.result.pane` として返します。
+
+ペインを別のワークスペースへ移動すると、ワークスペース修飾付きのペイン ID が変わります。`pane move` の後は `.result.move_result.pane.pane_id` を使い、以前の値が必要なら `.result.move_result.previous_pane_id` を参照してください。実行中プロセスは起動時の Herdr 環境を保ちますが、以前の `HERDR_PANE_ID` はそのターミナルの別名として残るため、`--current` は引き続き安全に使えます。移動後に始めるコマンドはエージェント名で解決できますが、すでに進行中の待機は `agent_not_running` で終了します。
+
+シェル、テスト、サーバー、CI ウォッチャーなどの通常のターミナルプロセスにはペインコマンドを使います。どのエージェントが動いているか、または状態が `working`、`blocked`、`done`、`idle`、`unknown` のどれかを Herdr に判断させる場合はエージェントコマンドを使います。
+
+## エージェントの識別子と起動
+
+`w1:p2` のようなペイン ID はターミナルの場所を識別します。`reviewer` のようなエージェント名は、そのペインに現在いるエージェントの扱いやすい別名です。名前は `[a-z][a-z0-9_-]{0,31}` に一致し、ライブエージェント間で一意でなければなりません。エージェントが終了、解放、または置換されると別名は消えます。ペイン自体の恒久的な名前ではありません。
+
+エージェントコマンドは、一意なライブ名、または現在そのエージェントをホストしているペイン ID のどちらでも指定できます。
+
+利用可能なシェルペインとは、対話シェルのプロンプトに戻っており、フォアグラウンドをシェル自身が所有し、フォアグラウンドのコマンド、エディタ、エージェントが動いていないペインです。`agent start` の前にプロンプトへ戻してください。
+
+`--kind` は対応済みエージェントとその標準実行ファイルを選びます。対応する kind は `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`omp`、`mastracode`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli`、`qwen`、`letta`、`maki`、`muse` です。`--` より後の引数は、その実行ファイルへそのまま渡されます。
+
+成功した `agent start` は、同じターミナルで期待したエージェントを検出し、対話入力の準備ができたと Herdr が判断してから返ります。起動中の検出状態が `blocked` の場合、コマンドは直ちに `agent_not_ready` を返します。名前は `agent read` と `agent send-keys` で引き続き使用でき、検出状態が `idle` になるとプロンプトを送信できるようになります。起動待機はデフォルトで 30 秒です。`--timeout` は 3000 より大きく 300000 以下のミリ秒で指定します。
+
+```bash
+herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
+```
+
+手動で起動したエージェントも自動検出され、ペイン ID で指定できます。人が読みやすい安定した対象名が必要なら名前を付けます:
+
+```bash
+herdr agent get w1:p2
+herdr agent rename w1:p2 reviewer
+```
+
+## 操作面を選ぶ
+
+| 目的 | コマンド |
+| --- | --- |
+| シェルコマンドを実行して送信する | `pane run` |
+| Enter を付けずに文字列を送る | `pane send-text` |
+| ターミナルキーや修飾キーの組み合わせを送る | `pane send-keys` |
+| 文字列や正規表現を待つ | `pane wait-output` |
+| 既存のペインで対応済みエージェントを起動する | `agent start` |
+| プロンプトを送信し、必要なら完了を待つ | `agent prompt` |
+| エージェントの対話 UI にキーを送る | `agent send-keys` |
+| エージェントのライフサイクル状態を待つ | `agent wait` |
+
+`agent prompt` はテキストを送信し、短い遅延の後にエンコード済み Enter を送信します。ターミナルの現在の bracketed paste モードを尊重します。working 中のエージェントにも送信できます。エージェントがすでに `blocked` の場合は、ターミナル入力を送信せずに `agent_blocked` を返します。ダイアログを確認し、意図した応答には `agent send-keys` を使ってください。`esc`、`up`、`enter`、`ctrl+c` のような操作には `agent send-keys` を使います。`escape` も `esc` のエイリアスとして使えます。意図的に生のターミナルを操作したい場合は、ペイン入力コマンドを使ってください。
+
+ペイン入力は、現在のプロセスに関係なくターミナルを指定します。エージェント入力はライブエージェントを解決し、そのエージェントがペインを制御しなくなっていれば操作を拒否します。
+
+`agent prompt --wait` は、エージェントがすでに `blocked` の場合、入力も待機も開始せずに `agent_blocked` を返します。それ以外は、プロンプトと遅延した Enter を順序付きの 1 回の送信として書き込んでから待機します。Windows の Codex では Enter の前にペースト境界が送られるため、送信はプロンプトのサイズに依存しません。呼び出し側のタイムアウトには送信時間も含まれます。別の non-working 状態から始まった場合、送信後に最大 5 秒間、`working` または `blocked` を観測するまで待ちます。観測できなければ `agent_prompt_stalled` を返し、呼び出し側のタイムアウトが先に切れた場合は通常の `timeout` エラーを返します。これにより、無関係な `idle`、`done`、またはセッションの変化によって待機が誤って完了することを防ぎます。活動を観測した後、要求された安定状態を待ちます。個々のターンは追跡しません。エージェントがすでに working の場合、進行中ターンの完了が待機を満たすことがあります。単独の `agent wait` は現在のエージェントを監視し、すでに状態が一致していれば即座に返ります。どちらもデフォルトでは `idle`、`done`、`blocked` を待ちます。複数の正確な状態を許可するには、`--until idle --until done` のように `--until` を繰り返します。`unknown` が必要な場合は `--until unknown` を明示してください。`agent prompt` では `--until` に `--wait` が必要です。
+
+`idle` と `done` はどちらも入力可能な状態です。CLI/API はサーバーの既読状態を使い、未確認の idle を `done` とします。明示的な `pane focus` / `agent focus` は対象を既読にしますが、読み取りでは変わりません。各 TUI クライアントは表示済みの完了を独立して管理するため、Done バッジが CLI やほかのクライアントと異なる場合があります。`blocked` は承認または質問 UI を Herdr が認識した状態です。`unknown` はエージェントが存在するもののライフサイクルを確実に分類できない状態で、成功完了を意味しません。違いが重要なら正確な `--until` を指定してください。
+
+起動準備、idle な会話の復元、エージェント会話の切り替えは、作業の完了として数えません。起動直後に作業を始めるエージェントは、Herdr が先に idle プロンプトを確認しなくても最初のタスクを完了できます。エージェントのレスポンスには `completion_seq` が含まれる場合があり、誰が確認したかに関係なく、現在の idle 遷移が完了した作業であることを示します。これはその遷移の `state_change_seq` と一致し、起動やセッション変更では設定されません。古いサーバーではこのフィールドが省略される場合があります。古いサーバーに接続したクライアントは、観測した working 状態を使って Done バッジを保護するため、更新の合間に開始して終了したターンを見逃す可能性があります。
+
+タイムアウトや `agent_prompt_stalled` は、入力が送られていないことを保証しません。二重送信を避けるため、再試行の前にエージェントを読み取ってください。ID とエージェント名はサーバーごとに独立しています。TUI で別のマシンを選んでも、既存ペイン内の CLI コマンドの接続先は変わりません。
+
+`pane wait-output` はエージェントのライフサイクルを解釈しません。選択したターミナルスナップショットをポーリングし、最初にすぐ検索するため、すでに存在する文字列も一致します。デフォルトのソース名は `recent` で、直近 80 行の描画済みターミナル行を折り返し前の出力として扱います。`--lines` でその行数を変更でき、`--regex` は Rust の正規表現構文で 1 行ずつ一致します。
+
+CLI では、`pane read` と `agent read` のどちらもターミナルテキストを直接出力します。デフォルトは ANSI エスケープを除去した UTF-8 テキストです。ソースに装飾が含まれる場合、`--format ansi` または `--ansi` でエスケープを残します。`detection` ソースは常にプレーンテキストです。recent 系ソースでは、`--lines N` は折り返し解除の前に末尾の N 描画行を選び、省略時は 80 行です。`visible` と `detection` では、省略時にスナップショット全体を返し、指定時は改行で区切られた末尾 N 行を返します。socket API ではテキストを `.result.read.text` に返します。
+
+## 代替画面の履歴読み取り
+
+Claude Code や OpenCode などの全画面エージェントは、トランスクリプト履歴を Herdr のホスト側スクロールバックではなく、ターミナルの代替画面に描画します。認識済みのエージェントが idle でトランスクリプトの末尾にあり、`--lines` が表示画面より多い行を要求した場合、`recent` または `recent-unwrapped` のテキスト読み取りはエージェントのマウススクロール操作を自動的に使います。Herdr は重なり合うページを収集し、読み取りが完了する前にビューポートを末尾へ戻します。そのペインに対象エージェントがいる場合、`pane read` にも同じ動作が追加オプションなしで適用されます。
+
+その他の読み取りは受動的なままです。`visible`、`detection`、ANSI 読み取り、出力待機と購読、手動でスクロールされたエージェント、直接アタッチ中のペイン、マウスホイール入力を報告しないアプリケーションでは、Herdr はアプリケーションのビューポートを動かしません。明示的な `agent read --lines N` が代替画面の履歴を必要とする場合、エージェントが working、blocked、または unknown の間は `agent_not_idle` を返します。idle になるまで待って再試行するか、`--source visible` を使ってください。その他の recent 読み取りは従来どおり、利用可能な画面とホスト側スクロールバックを返します。
+
+完全な応答を取得できない場合は、一時ディレクトリの Markdown ファイルに応答を書き込み、ファイルパスだけを返すようエージェントに依頼して、そのファイルを直接読み取ってください。
+
+成功した `agent start`、`agent prompt`、`agent wait` は現在のエージェントを `.result.agent` に返します。`pane wait-output` は `.result.pane_id`、`.result.matched_line`、一致したスナップショット `.result.read` を返します。
+
+wait コマンドにはデフォルトのタイムアウトがなく、無期限に待機できます。タイムアウトやサーバーエラーでは JSON エラーを stderr に出して終了コード 1、CLI 構文エラーでは終了コード 2 を返します。
+
+## レシピ
+
+補助エージェントを起動して作業を渡し、その作業が落ち着くまで待ちます:
+
+```bash
+split=$(herdr pane split --current --direction right --no-focus)
+review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
+herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
+herdr agent prompt reviewer "Review the current diff" --wait --timeout 120000
+herdr agent read reviewer --source recent-unwrapped --lines 120
+```
+
+エージェントが入力を求めるまで待ち、内容を確認して対話 UI を操作します:
+
+```bash
+herdr agent wait reviewer --until blocked --timeout 120000
+herdr agent read reviewer --source recent-unwrapped --lines 80
+herdr agent send-keys reviewer esc
+```
+
+通常のプロセスを実行し、エージェントとして扱わずに出力を待ちます:
+
+```bash
+herdr pane run w1:p3 "just test --watch"
+herdr pane wait-output w1:p3 --regex "passed|failed" --timeout 120000
+```
+
+コマンドとオプションの完全な一覧は [CLI リファレンス](/ja/docs/cli-reference/) を参照してください。シェル補完でも同じコマンドツリーを対話的に確認できます。
@@ -0,0 +1,67 @@
+---
+title: エージェントスキルファイル
+description: Claude Code などのコーディングエージェントに Herdr の使い方をインストールします。
+---
+
+Herdr は再利用可能なエージェントスキルファイルを [`skills/herdr/SKILL.md`](https://github.com/herdrdev/herdr/blob/master/skills/herdr/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 指示ファイルです。Herdr がすでにインストールされている場合は、`herdr --skill` を実行すると、そのバイナリのリリースと一致する同梱コピーを表示できます。
+
+## インストールする
+
+`npx skills` でスキルをインストールします:
+
+```bash
+npx skills add herdrdev/herdr --skill herdr -g
+```
+
+スキルがリポジトリのルートにあったときにインストールした場合は、`skills update` ではなく、この add コマンドを一度再実行してください。大きすぎる既存のコピーが置き換えられ、新しい場所が記録されます。
+
+`-g` フラグは、対応エージェントにグローバルインストールします。現在のプロジェクトにインストールする場合は `-g` を省略してください。
+
+手動でのフォールバックおよび信頼できるソースとしては、リポジトリのコピーを使ってください:
+
+```text
+https://github.com/herdrdev/herdr/blob/master/skills/herdr/SKILL.md
+```
+
+スキルシステムを持つエージェントには、このファイルを `herdr` という名前のスキルとしてインストールしてください。スキルシステムを持たないエージェントには、ファイルの内容をプロジェクト指示またはユーザー指示に貼り付けてください。
+
+インストール後、Herdr の中でエージェントを起動します:
+
+```bash
+herdr
+claude
+```
+
+他のコーディングエージェントを Herdr のペインで使っても構いません。重要なのは、エージェントのプロセスが Herdr 内で動作していて `HERDR_ENV=1` が利用できることです。
+
+## 安全ルール
+
+このスキルはひとつのガードレールから始まります: `HERDR_ENV=1` が設定されていない場合、エージェントは停止して、Herdr 管理下のペイン内で動作していないと伝えるべきです。
+
+これにより、Herdr の外にいるエージェントが自分のものではないセッションを制御しようとするのを防ぎます。
+
+## エージェント向けリファレンス
+
+コマンドの完全なガイドはスキルファイル自体にあります。ペイン ID、`pane split`、`pane run`、`pane read`、`pane wait-output`、`agent wait`、ワークスペースとタブのコマンド、協調動作のレシピを扱っています。
+
+ソースファイルはこちら:
+
+[GitHub で `SKILL.md` を開く →](https://github.com/herdrdev/herdr/blob/master/skills/herdr/SKILL.md)
@@ -0,0 +1,175 @@
+---
+title: エージェント
+description: Herdr で使えるコーディングエージェント (Herdr が対応するもの、自ら Herdr に対応するもの) と、エージェント状態の仕組み。
+---
+
+Herdr は複数のコーディングエージェントを同時に動かすために作られています。各エージェントは、シェル、ログ、プロンプト、実行中プロセスをそのまま保った実際のターミナルペインの中にいます。Herdr はどのペインにエージェントがいるかを追跡し、その状態をタブとワークスペースに集約し、すべてのターミナルを手作業で見回る代わりに、注意が必要なペインへ直接ジャンプできるようにします。
+
+スクリプトや別のエージェントから連携させる方法は、[エージェント自動化](/ja/docs/agent-automation/) を参照してください。
+
+## 対応エージェント
+
+エージェントが Herdr 対応になる方法は 2 つあります。Herdr がそのエージェントに対応するか、エージェント自身が Herdr に対応するかです。どちらでも、各エージェントの `idle`、`working`、`blocked` 状態が表示され、完了時や対応が必要なときに通知され、スクリプトから待機できます。
+
+それ以外のエージェントも Herdr のペインで普通に動きます。単に通常のターミナルとして表示されるだけです。
+
+### Herdr が対応するエージェント
+
+Herdr はこれらのエージェントを認識し、画面の表示から状態を読み取ります。Herdr サーバーの再起動後に同じセッションへ戻るには、`herdr integration install <name>` でエージェントのインテグレーションをインストールしてください。各インテグレーションがインストールする内容は[インテグレーション](/ja/docs/integrations/)を参照してください。
+
+| エージェント | インテグレーション | 備考 |
+| --- | --- | --- |
+| Claude Code | `claude` | |
+| Codex | `codex` | |
+| GitHub Copilot CLI | `copilot` | |
+| Cursor Agent CLI | `cursor` | |
+| OpenCode | `opencode` | 状態も報告 |
+| Pi | `pi` | 状態も報告 |
+| OMP | `omp` | 状態にはインテグレーションが必要 |
+| Droid | `droid` | |
+| Devin CLI | `devin` | |
+| Kimi Code CLI | `kimi` | 状態も報告 |
+| Kilo Code CLI | `kilo` | 状態も報告 |
+| Hermes Agent | `hermes` | |
+| Qoder CLI | `qodercli` | |
+| Qwen Code | `qwen` | |
+| Letta Code | `letta` | CLI からのみインストール |
+| MastraCode | `mastracode` | 状態にはインテグレーションが必要 |
+| Grok CLI | `grok` | |
+| Antigravity CLI | `antigravity-cli` | |
+| Amp | なし | 状態のみ |
+| Kiro CLI | なし | 状態のみ |
+| Maki | なし | 状態のみ |
+| Gemini CLI | なし | 状態のみ、テストは限定的 |
+| Cline | なし | 状態のみ、テストは限定的 |
+
+### Herdr に対応するエージェント
+
+これらのエージェントは自分の状態を Herdr に報告します。インストールするものはありません。Herdr のペインで実行するだけです。
+
+<ul class="agent-logos">
+  <li><a href="https://commandcode.ai"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/command-code.svg')" }} aria-hidden="true"></span>Command Code</a></li>
+  <li><a href="https://github.com/charmbracelet/crush"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/crush.svg')" }} aria-hidden="true"></span>Crush</a></li>
+  <li><a href="https://kiro.dev/cli/"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/kiro-mask.svg')" }} aria-hidden="true"></span>Kiro CLI</a></li>
+  <li><a href="https://dev.meta.ai/products/muse-code"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/muse-code.svg')" }} aria-hidden="true"></span>Muse Code</a></li>
+  <li><a href="https://github.com/PrimeIntellect-ai/prime-agent"><span class="agent-logo" style={{ '--logo': "url('/assets/agent-icons/prime-agent.svg')" }} aria-hidden="true"></span>Prime Agent</a></li>
+</ul>
+
+resume コマンドも報告するエージェントは、Herdr サーバーの再起動後に同じセッションで戻ります。
+
+コーディングエージェントを開発している場合は、[エージェントに Herdr 対応を追加する](/ja/docs/add-herdr-support/)でこの一覧に加わる方法を確認できます。Herdr の CLI かソケットを数回呼ぶだけで、Herdr 側の変更は不要です。
+
+## 状態の仕組み
+
+Herdr が対応するエージェントでは、Herdr は各ペインでエージェントのプロセスを見つけ、スクロールした位置ではなくペインのライブな下部を読みます。検出マニフェストのルールが、その画面が `idle`、`working`、`blocked` のどれかを判定します。インテグレーションが状態も報告している場合、Herdr は画面を読む代わりにその報告を使います。
+
+Herdr に対応するエージェントでは、エージェント自身の報告が状態を決めます。
+
+## VM とサンドボックスラッパー
+
+Linux と macOS では、ホストから見えるラッパーが実際のエージェントプロセスを Herdr から隠すことがあります。ラッパーのコマンドに `HERDR_AGENT=<agent>` を設定して、どの既存エージェントのスクリーンマニフェストを使うべきか Herdr に伝えてください。たとえば、Linux では `HERDR_AGENT=claude fence -- claude`、macOS では `HERDR_AGENT=claude nono run --profile claude-code -- claude` を実行します。このヒントはそのフォアグラウンドプロセスにスコープされます。VM やコンテナの内部だけで設定しても Herdr からは見えません。また、継承されるすべてのフォアグラウンドプロセスをそのエージェントとして扱いたいのでない限り、グローバルな export は避けてください。
+
+一部の制限された Linux ランタイムでは、ターミナルのフォアグラウンドプロセスグループが公開されません。ネイティブ検出が利用できない場合に直接の子プロセスグループ推論を有効にするには、Herdr サーバーを `HERDR_PROCESS_DETECTION=child-groups` 付きで起動します。ネイティブ検出が引き続き優先され、デフォルトの `native` モードではこの推論を行いません。このオプトインモードはベストエフォートで、新しいバックグラウンドジョブをフォアグラウンドと誤認する可能性があります。この変数はサーバーが読み取るため再起動が必要です。アタッチするクライアントではなく、リモートサーバーの環境に設定してください。
+
+## blocked 状態
+
+スクリーンマニフェスト方式のエージェントでは、blocked の検出は意図的に厳格です。Herdr が `blocked` と判定するのは、ライブの下部バッファスナップショットが既知の承認・質問・許可 UI にマッチしたときだけです。既知のエージェントでどのマニフェストルールにもマッチしない場合、Herdr は `idle` にフォールバックし、explain の出力ではそのフォールバックに `default_known_agent_idle_fallback` というラベルを付けます。
+
+見慣れない新しいエージェントプロンプトは、Herdr がその画面の形を学習するまで、`blocked` ではなく `idle` と表示されることがあります。検出自体は入力を送りませんが、誤った idle 状態を信頼する自動処理は承認ダイアログへ入力してしまう可能性があります。予期しないプロンプトでは次の入力を送る前に画面を確認してください。idle は操作を承認する許可ではありません。
+
+Antigravity と Grok は、バックグラウンドのタスク、モニター、サブエージェントが動いていても、プロンプトに戻ると idle と判定されます。`agent wait` と `agent prompt --wait` はエージェントの状態を監視し、それらのジョブの完了は待ちません。
+
+Ctrl+Z でエージェントを中断しても、同じプロセスがシェルやエージェント以外のコマンドの背後で生きている間は、名前、セッション参照、フックの権限を保持します。`fg` で戻ると同じ識別情報を使えます。別の認識済みエージェントがフォアグラウンドを引き継ぐ場合は対象外です。識別情報が残っていても、中断中のエージェントが入力を受け取れるとは限りません。送信前にペインを確認してください。
+
+## 検出マニフェスト
+
+バンドルされたマニフェストは Herdr の内部にあります。Herdr は herdr.dev でリモートマニフェストの更新も確認し、有効なエージェント別ルール更新を Herdr の再起動なしで自動適用します。リモートマニフェストは Herdr の state ディレクトリに保存されます。バックグラウンドのリモートマニフェスト確認を無効にするには `[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 セッションの中までは調べません。シェルフレームワークが Herdr 内で自動的に tmux に入る場合、Herdr はペインのプロセスとして背後のエージェントではなく `tmux` を見ることになります。
+
+`TMUX` が未設定のときにシェルが自動的に tmux に接続する場合、シェルの起動条件を更新して Herdr のペインを除外してください。Herdr のペイン内から外側の tmux セッションに再接続すると、ターミナルのサイズが再帰的に縮小し、画面がちらつくことがあります。既存の条件に、tmux を実行する前に `HERDR_ENV` の確認を追加します:
+
+```zsh
+if [[ -z ${TMUX:-} && ${HERDR_ENV:-} != 1 ]]; then
+  tmux new-session -A -s my-session
+fi
+```
+
+## 状態のロールアップ
+
+サイドバーは状態を上位へ集約します。
+
+blocked なエージェントは、そのペイン、タブ、ワークスペースを blocked に見せます。working なエージェントはワークスペースをアクティブに見せます。done なエージェントは、あなたが確認するまで表示され続けます。
+
+これが Herdr の中心的なワークフローです: 複数のエージェントを起動し、並行して働かせ、サイドバーでどのプロジェクトが判断を必要としているか、どれがまだ実行中か、どれがレビュー待ちかを把握します。
+
+## カスタムエージェントラベル
+
+表示用にエージェントターゲットの名前を変えられます:
+
+```bash
+herdr agent rename w1:p1 reviewer
+herdr agent rename reviewer --clear
+```
+
+ターゲットには一意なライブエージェント名、または現在そのエージェントをホストしているペイン ID を使います。ターミナル ID とエージェント kind のラベルだけでは指定できません。
+
+## カスタムステータスラベル
+
+インテグレーションは、ライフサイクル状態を意味的な状態としてのみ報告します。表示のカスタマイズは、ペインメタデータのトークンとして別に追加します。
+
+```bash
+herdr pane report-agent w1:p1 \
+  --source custom:indexer \
+  --agent docs-bot \
+  --state working
+
+herdr pane report-metadata w1:p1 \
+  --source custom:indexer-display \
+  --token summary=indexing
+```
+
+`state` は wait、通知、ロールアップを制御します。`summary` トークンは表示専用で、エージェントサイドバー行では `$summary` として使えます。
+
+エージェントサイドバー行では、`terminal_title` または `terminal_title_stripped` も任意で使えます。どちらもデフォルト行には含まれません。前者は安全性のために正規化された最新の OSC 0/2 ターミナルタイトルを表示し、後者は先頭にある認識済みのアクティビティまたはスピナーのグリフ 1 つと、それに続く空白を除去します。これらの値は Herdr サーバーが所有し、コールドリスタートをまたいで保持されません。また、メタデータのタイトルや意味的なエージェント状態から独立しています。そのため、除去後のテキストが同じなら、スピナーのアニメーションで生のタイトルが変わってもペイン更新は発行されません。
+
+## エージェントに直接アタッチする
+
+完全な 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>` を使ってください。
@@ -0,0 +1,505 @@
+---
+title: CLI リファレンス
+description: セッション、ワークスペース、タブ、ペイン、通知、エージェント、wait、インテグレーション、ステータスのための Herdr コマンド。
+---
+
+Herdr の CLI は、インテグレーションやエージェントが使うのと同じローカルソケット API を通じて、実行中のサーバーと通信します。
+
+ほとんどのコマンドは JSON レスポンスを出力します。決定的な自動化が欲しいときはスクリプトから使ってください。
+
+## 起動とステータス
+
+```bash
+herdr                         # デフォルトセッションを起動またはアタッチ
+herdr --remote workbox        # SSH 越しにアタッチ (ローカルのキーバインドを使用)
+herdr --default-config        # デフォルト設定を表示
+herdr update                  # 設定済みチャンネルからダウンロードしてインストール
+herdr completion zsh          # zsh 補完スクリプトを生成
+herdr channel show            # stable または preview を表示
+herdr channel set preview     # プレビュービルドにオプトイン
+herdr channel set stable      # 直接インストールを安定版に戻す
+herdr --version               # バージョンを表示
+```
+
+起動と更新の任意オプション:
+
+- デフォルトではなく名前付きセッションを使う場合は `--session <name>` を追加します。
+- リモート接続でサーバーのキーバインドを使う場合は `--remote-keybindings server` を追加します。
+- 実験的なライブハンドオフには、`herdr --remote` または `herdr update` で明示的な `--handoff` が必要です。通常のセットアップや接続には使いません。[更新](/ja/docs/install/)を参照してください。
+
+ステータスコマンド:
+
+```bash
+herdr status
+herdr status server
+herdr status client
+```
+
+API スキーマコマンド:
+
+```bash
+herdr api schema
+herdr api schema --json
+herdr api schema --output herdr-api.schema.json
+```
+
+`herdr api schema` は、インストール済みバイナリに同梱されたソケットプロトコルスキーマの短い概要を表示します。完全な JSON Schema ドキュメントが欲しいときは `--json` を使い、ファイルに書き出すには `--output PATH` を使ってください。
+
+## 保存済み SSH マシン
+
+```bash
+herdr machine list
+herdr machine add workbox
+herdr machine add workbox --label "Build machine"
+herdr machine rename <profile-id> --label "New name"
+herdr machine disable <profile-id>
+herdr machine enable <profile-id>
+herdr machine remove <profile-id>
+```
+
+対話型ターミナルでは、`machine add` は実行中のセッションを検出し、複数あれば選択できます。実行中のセッションがない場合や Herdr がインストールされていない場合は `default` を使います。インストール済みバイナリへの問い合わせに失敗した場合は、明示的な選択が必要です。検出を省略するには `--remote-session <name>` を追加します。非対話型コマンドでは、このフラグがない限り `default` を使います。スクリプトでは `machine list` に `--json` を追加できます。詳しくは[マシンへの接続](/ja/docs/connecting-machines/)を参照してください。
+
+`machine add` はリモート側の Herdr が必要な機能を備えているか確認し、必要な場合だけ承認を得てインストールまたは更新します。指定したセッションのバックグラウンドサーバーを起動してからプロファイルを保存します。互換性があればリリースバージョンは一致しなくてもかまいません。インストールや再起動の承認が必要な場合は、対話型ターミナルで実行してください。セットアップが失敗またはキャンセルされた場合、プロファイルは保存されません。実行中サーバーの置き換えには明示的な承認が必要で、デフォルトの回答は No です。停止するとペインのプロセスも終了します。`machine add` は実験的なハンドオフを暗黙に有効にしません。
+
+変更は、開いているローカルの Herdr クライアントに通常 1 秒以内に自動反映されます。追加または有効化したマシンにはバックグラウンドで接続し、名前の変更では再接続しません。削除または無効化すると、そのマシンだけが切断され、リモートセッションは動き続けます。表示中のマシンを削除すると Local に戻ります。Local に接続できない場合は、再接続するまで利用不可と表示します。各プロファイルは、不透明な ID、ラベル、SSH 接続先、明示的なリモートセッション名、有効状態をクライアントの状態ファイルに保存します。パスワード、秘密鍵、その他の SSH 認証情報は保存しません。
+
+`herdr machine status [<label-or-id>] [--json]` は SSH とリモート Herdr を非対話式で確認します。`reachable` は今回の確認結果で、TUI の接続状態ではありません。ターミナルで `herdr machine reconnect <label-or-id>` を実行すると認証と検証を行いますが、インストールや更新は行いません。開いているクライアントは 30 秒以内に再試行します。`! auth` または `! error` をクリックすると最新のエラーと CLI コマンドを表示します。折りたたみ時は `!` です。対応環境は [SSH 認証の復旧](/ja/docs/connecting-machines/#ssh-認証の復旧)を参照してください。セットアップには `herdr --remote workbox` を使い、名前付きセッションの場合だけ `--session <name>` を追加します。
+
+ワークスペース、タブ、ペインの ID とエージェント名はサーバーごとに独立しています。UI での選択は CLI の接続先を変えません。保存済み SSH マシンへ API コマンドを送るには、グローバルな**プレフィックス** `--machine <label-or-id>` を指定します。
+
+```bash
+herdr --machine "Build machine" agent list
+herdr --machine <profile-id> pane list
+herdr --machine "Build machine" agent prompt w1:p1 "review this change"
+herdr --machine "Build machine" worktree create --cwd /srv/project --branch review
+```
+
+有効なプロファイル ID または一意のラベル（大文字・小文字を区別）を指定します。任意の SSH ホスト名は使えません。保存済みのリモートセッションを使うため、`--session` や `--remote` との併用はエラーです。省略時のローカル動作は変わりません。
+
+対応するのは `workspace`、`worktree`、`tab`、`pane`、`notification`、`agent`（`attach` とローカルの `explain --file` 以外）、`api snapshot`、`status server`、API ベースのプラグイン操作（`link`、`unlink`、`enable`、`disable`、`list`、`action`、`log`、`pane`）です。サーバー操作は `stop`、`reload-config`、`agent-manifests`、`reload-agent-manifests` に対応します。ローカルのインストール・設定、プラグインのインストール、セッション管理、対話的な端末接続は転送しません。
+
+JSON API を非対話 SSH で転送します。API の内容を SSH のシェルコマンドに埋め込むことはありません。開いた TUI は不要で、サーバーのインストール・起動・再起動も自動では行いません。ローカル CLI とリモート Herdr を更新し、実行中サーバーの API プロトコルとの互換性を保ってください。認証、接続、互換性のエラーで Local にフォールバックしたり、要求を自動再送したりすることはありません。
+
+呼び出し元のローカルペイン ID は継承しません。リモート ID を明示してください。`--current` でローカルペインを指定することはできません。リモート worktree パスには絶対パス、`~`、または `~/` で始まるパスを指定します（サーバー側で展開）。プラグインの link パスは絶対パスが必要です。対象は 1 台ずつで、一覧の統合や別の TUI の接続を使った転送は含みません。
+
+## シェル補完
+
+```bash
+herdr completion zsh
+herdr completions zsh
+herdr completion bash
+herdr completion fish
+herdr completion powershell
+herdr completion elvish
+```
+
+`completion` はスクリプトを標準出力に表示します。`completions` はエイリアスです。一時的な zsh セッションでは、スクリプトを直接読み込めます:
+
+```bash
+source <(herdr completion zsh)
+```
+
+永続的な zsh 設定では、生成された `_herdr` 関数を `compinit` が実行される前の `fpath` 上に置いてください:
+
+```bash
+mkdir -p ~/.zfunc
+herdr completion zsh > ~/.zfunc/_herdr
+```
+
+その後、`.zshrc` に次の内容があることを確認してください:
+
+```zsh
+fpath=(~/.zfunc $fpath)
+autoload -Uz compinit
+compinit
+```
+
+## サーバー
+
+```bash
+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 トーストにのみ影響します。`--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 report-metadata <workspace_id> --source ID [--token NAME=VALUE] [--clear-token NAME] [--seq N] [--ttl-ms N]
+herdr workspace close <workspace_id> [--group]
+```
+
+フォーカスを奪わずにワークスペースを作成します:
+
+```bash
+herdr workspace create --cwd ~/project --label api --no-focus
+```
+
+ワークスペースは最上位のプロジェクトまたは作業コンテキストです。作成時に最初のタブとルートペインも作られます。JSON レスポンスの `.result.workspace.workspace_id`、`.result.tab.tab_id`、`.result.root_pane.pane_id` から各 ID を取得できます。
+
+## Worktree
+
+```bash
+herdr worktree list [--workspace ID | --cwd PATH] [--trust-repository]
+herdr worktree create [--workspace ID | --cwd PATH] [--branch NAME] [--base REF] [--path PATH] [--label TEXT] [--focus] [--no-focus] [--trust-repository]
+herdr worktree open [--workspace ID | --cwd PATH] (--path PATH | --branch NAME) [--label TEXT] [--focus] [--no-focus] [--trust-repository]
+herdr worktree remove --workspace ID [--force] [--trust-repository]
+```
+
+worktree は、Git チェックアウトの出自情報を持つ通常の Herdr ワークスペースです。`worktree create` は Git worktree のチェックアウトを作成し、ワークスペースとして開き、親リポジトリのワークスペースとグループ化します。`--branch` が既存のローカルブランチを指す場合はそれをチェックアウトし、そうでなければ `--base` または `HEAD` からブランチを作成します。`--path` がない場合、チェックアウトは `<worktrees.directory>/<repo>/<branch-slug>` の下に作成されます。
+
+`workspace close` は Herdr の状態だけを閉じます。リンクされた worktree ワークスペースが開いている間に親ワークスペースを閉じるには `--group` が必要です。指定しない場合、グループは開いたままになり `workspace_group_close_required` が返されます。`worktree remove` が明示的なチェックアウト削除の経路です。`git worktree remove` を実行し、ブランチは決して削除せず、Git がダーティなチェックアウトを拒否する場合は `--force` が必要です。
+
+Git はデフォルトで、別のユーザーが所有するリポジトリを拒否します。リポジトリを別途確認済みの場合は `--trust-repository` を渡すと、解決されたパスをそのコマンドでのみ信頼します。Herdr は Git 設定を変更しません。
+
+## タブ
+
+```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>
+```
+
+タブはワークスペース内の別のターミナルレイアウトです。`--workspace` を省略すると、`tab create` はアクティブなワークスペースを使い、存在しなければ失敗します。JSON レスポンスの `.result.tab.tab_id` と `.result.root_pane.pane_id` から ID を取得できます。ワークスペースの最後のタブを閉じると、そのワークスペースも閉じられます。`ui.confirm_close` が有効で、親ワークツリーの最後のタブを閉じるとワークツリーグループ全体が閉じられる場合、`tab close` は `confirmation_required` エラーを返します。
+
+`ui.confirm_close` が有効な場合、キーバインドやタブ／ペインメニューからワークスペースの最後のタブ、または唯一のペインを閉じる前に、TUI が確認を求めます。通常のペイン終了や CLI/API による終了は引き続き即座に実行されます。
+
+ワークスペースとタブの作成、およびペインの分割は、デフォルトではフォーカスを変えません。`--focus` は新しいレイアウトを選択し、`--no-focus` はデフォルトを明示します。`--cwd` がない場合、新しいターミナルは `terminal.new_cwd` の設定に従い、デフォルトでは元のペインまたはワークスペースを引き継ぎます。各 `--env KEY=VALUE` は新しいルートシェルの環境変数を追加または置換します。
+
+## ペイン
+
+```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>
+```
+
+`--current` を受け付けるペインコマンドは、Herdr ペイン内から実行した場合、呼び出し元の `HERDR_PANE_ID` を使います。`pane split` では、明示したペイン ID または `--pane ID` がそのペインを分割します。対象を省略すると `HERDR_PANE_ID` があれば呼び出し元ペインを、なければフォーカス中のペインを使います。`--current` は呼び出し元ペインを必須とし、`HERDR_PANE_ID` がない場合はエラーになります。分割レスポンスでは、新しいペイン ID は `.result.pane.pane_id` にあります。
+
+`pane move` の後続コマンドには `.result.move_result.pane.pane_id` を使います。別ワークスペースへの移動ではワークスペース修飾付きのペイン ID が変わり、以前の値は `.result.move_result.previous_pane_id` に残ります。実行中プロセスの `HERDR_PANE_ID`、`HERDR_TAB_ID`、`HERDR_WORKSPACE_ID` は起動時の値のままですが、Herdr は以前のペイン ID をそのターミナルの別名として保持するため、`--current` を使うペインコマンドは引き続き解決できます。ライブエージェント名もターミナルに追従します。
+
+出力を読む:
+
+```bash
+herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi] [--raw]
+herdr pane read <pane_id> --source visible --ansi
+herdr pane read <pane_id> --source recent-unwrapped --lines 120
+```
+
+`pane read` は UTF-8 のターミナルテキストを直接出力します。デフォルトでは ANSI エスケープを除去し、ソースに装飾が含まれる場合は `--format ansi` または `--ansi` で保持します。`detection` ソースは常にプレーンテキストです。recent 系ソースでは、`--lines N` は折り返し解除の前に末尾の N 描画行を選び、省略時は 80 行です。`visible` と `detection` では、省略時にスナップショット全体を返し、指定時は改行で区切られた末尾 N 行を返します。`agent read` も同じ出力と行数の動作です。
+
+入力を送る:
+
+```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` のエイリアスとして受け付けられます。
+
+標準表記は `esc` ですが、`escape` も使えます。
+
+`pane run` は現在の bracketed paste モードを尊重し、テキストと Enter をアトミックに送信します。コマンドには `send-text` + `send-keys Enter` よりこちらを使ってください。個別の送信操作は低レベルのままで、コマンドを送信しません。
+
+カスタムフックからエージェント状態を報告する:
+
+```bash
+herdr pane report-agent <pane_id> \
+  --source ID \
+  --agent LABEL \
+  --state idle|working|blocked|unknown \
+  [--message TEXT] \
+  [--seq N] \
+  [--agent-session-id ID] \
+  [--agent-session-path PATH] \
+  [-- RESUME_COMMAND...]
+
+herdr pane report-agent-session <pane_id> \
+  --source ID \
+  --agent LABEL \
+  [--seq N] \
+  [--agent-session-id ID] \
+  [--agent-session-path PATH] \
+  [--session-start-source SOURCE] \
+  [-- RESUME_COMMAND...]
+
+herdr pane release-agent <pane_id> \
+  --source ID \
+  --agent LABEL \
+  [--seq N]
+```
+
+`report-agent-session` はライフサイクル状態を報告せずにネイティブセッション識別子を更新します。`release-agent` は、そのエージェントプロセスが終了したときに、そのソースのライフサイクル権限を終了します。
+
+`--` の後の引数は、サーバー再起動後にこのセッションを再開するために Herdr が実行するコマンドです。最初の引数は `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] \
+  [--state-label STATUS=TEXT] \
+  [--clear-state-labels] \
+  [--token NAME=VALUE] \
+  [--clear-token NAME] \
+  [--seq N] \
+  [--ttl-ms N]
+```
+
+`STATUS` は `idle`、`working`、`blocked`、`done`、`unknown` のいずれかです。`--agent` と `--applies-to-source` は `--title`、`--display-agent`、`--state-label` だけを保護し、トークンパッチは保護しません。トークンのクリアまたは TTL の更新は報告側が管理します。表示名を変えるには `--display-agent` を使ってください。
+
+メタデータのテキストは保存前に正規化されます。Herdr は前後の空白を取り除き、制御文字を除去し、`--title`、`--display-agent`、各 `--state-label`、トークンの値を 80 文字に制限します。正規化後に空になったトークン値は、そのキーをクリアします。
+
+`--token` は名前付き表示値を設定し、`--clear-token` は削除します。指定しなかったトークンは変わりません。ペイントークンはエージェントサイドバー行で `$name` として、ワークスペーストークンはスペース行で使えます。TTL は、その呼び出しで更新した各トークンキーに個別に適用されます。
+
+`--source` と `--applies-to-source` は 80 文字以下で、ASCII の英字、数字、コロン、ドット、アンダースコア、ハイフンのみを含められます。`--ttl-ms` はメタデータを自動失効させ、`1` から `86400000` ミリ秒の間でなければなりません。置き換え・クリア・ペインまたはワークスペースのクローズまで残るべきメタデータでは省略してください。`--seq` により、Herdr は同じ `--source` からの古い報告を無視できます。古い報告は API には受理されますが、ペイン状態には無視されます。ペインまたはワークスペースが存続する間、シーケンス付きトークン報告を送れる異なるソースは最大 32 個で、クリアや失効でもその枠は解放されません。
+
+## エージェント
+
+ペインとエージェントの使い分けや一連の連携例は、[エージェント自動化](/ja/docs/agent-automation/) を参照してください。
+
+```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-keys <target> <key> [key ...]
+herdr agent prompt <target> <text> [--wait] [--until STATUS]... [--timeout MS]
+herdr agent rename <target> <name>|--clear
+herdr agent focus <target>
+herdr agent wait <target> [--until STATUS]... [--timeout MS]
+herdr agent attach <target> [--takeover]
+herdr agent start <name> --kind KIND --pane ID [--timeout MS] [-- <agent-args...>]
+herdr agent explain <target> [--json|--verbose]
+herdr agent explain --file PATH --agent LABEL [--json|--verbose]
+```
+
+エージェントターゲットは、一意なライブエージェント名、または現在そのエージェントをホストしているペイン ID です。ターミナル ID とエージェント kind のラベルだけでは指定できません。`agent start` で起動するエージェントには名前が必須で、手動で起動したエージェントは名前なしのままペイン ID で指定します。
+
+`agent start` は既存の利用可能なシェルペインを起動対象にします。対話シェル自身がフォアグラウンドを所有し、フォアグラウンドのコマンド、エディタ、エージェントが動いていない必要があります。トポロジーは別に作成します。名前はライブエージェント間で一意で、`[a-z][a-z0-9_-]{0,31}` に一致する必要があります。対応する kind は `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`omp`、`mastracode`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli`、`qwen`、`letta`、`maki`、`muse` です。名前は現在のペイン占有者に属し、そのエージェントの終了、release、置換で消えます。一時的に検出できないだけでは消えません。
+
+成功した start は、期待したエージェントが同じターミナルを所有し、対話入力の準備ができてから返ります。起動中の検出状態が `blocked` の場合、コマンドは直ちに `agent_not_ready` を返します。名前は `agent read` と `agent send-keys` で引き続き使用でき、検出状態が `idle` になるとプロンプトを送信できるようになります。デフォルトの起動タイムアウトは 30000 ミリ秒で、明示する値は 3000 より大きく 300000 以下でなければなりません。
+
+`agent prompt` は現在の bracketed paste モードを尊重し、working 中でもテキストと遅延した Enter を順序付きの 1 回の送信として書き込みます。`--wait` なしの成功は書き込みの完了を示し、ターンの開始を保証しません。Windows の Codex では Enter の前にペースト境界が送られるため、送信はプロンプトのサイズに依存しません。呼び出し側のタイムアウトには送信時間も含まれます。エージェントがすでに `blocked` の場合は、入力を送信せずに `agent_blocked` を返します。`--wait` を使う場合、別の non-working 状態から受け付けたプロンプトでは、送信後の最大 5 秒間に `working` または `blocked` が観測される必要があります。観測できなければ Herdr は `agent_prompt_stalled` を返し、呼び出し側のタイムアウトが先に切れた場合は通常の `timeout` エラーを返します。これにより、無関係な `idle`、`done`、またはセッションの変化によって待機が誤って完了することを防ぎます。活動を観測した後、要求された最初の安定状態を待ちます。個々のターンは追跡しません。すでに working の場合、進行中ターンの完了が待機を満たすことがあります。`--until` は一致状態を絞り込み、`--wait` なしでは拒否されます。単独の `agent wait` は現在の状態が一致すれば即座に返ります。どちらもデフォルトは `idle`、`done`、`blocked` です。
+
+`idle` と `done` はどちらも入力可能な状態です。CLI/API はサーバーの既読状態を使い、未確認の idle を `done` とします。明示的な `pane focus` / `agent focus` は対象を既読にしますが、読み取りでは変わりません。各 TUI クライアントは表示済みの完了を独立して管理するため、Done バッジが CLI やほかのクライアントと異なる場合があります。`blocked` は承認または質問 UI を Herdr が認識した状態です。`unknown` はエージェントが存在するものの確実に分類できない状態で、作業の成功を意味しません。
+
+`agent send-keys` は `enter`、`up`、`esc`、`ctrl+c` などの論理キーを送ります。Herdr は 1 バイトも書き込む前に全キーを検証します。`agent read` は解決されたターミナルストリームを読み、`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 session control <target> [--takeover] [--cols N] [--rows N]
+herdr terminal session observe <target> [--cols N] [--rows N]
+herdr terminal title set <title>
+herdr terminal title clear
+```
+
+ダイレクトアタッチからは `ctrl+b q` でデタッチします。リテラルの `ctrl+b` は `ctrl+b ctrl+b` で送ります。
+`terminal session control` は、ペイン、ターミナル、エージェントを対象に書き込み可能なライブストリームを開きます。observe と同じ改行区切り JSON の `terminal.frame` と `terminal.closed` を出力し、標準入力から `terminal.input`、`terminal.resize`、`terminal.scroll`、`terminal.mouse`、`terminal.release` を受け取ります。制御クライアントは同時に 1 つだけで、`--takeover` で置き換えられます。`terminal.mouse` は 0 始まりのセル位置にマウスイベントを 1 つ送ります(例: `{"type":"terminal.mouse","action":"down","button":"left","column":12,"row":5}`)。`action` は `down`、`up`、`drag`、`move` のいずれかで、`button` は `left`(既定)、`right`、`middle`、`modifiers` は省略可能で Shift = 1、Ctrl = 2、Alt = 4 の組み合わせです(既定 0)。クリックは `down` の後に `up` を送ります。Herdr はアプリのマウスモードに合わせてエンコードし、マウス報告を有効にしていないアプリには送らないため、通常のシェルに余計な入力が届くことはありません。`move` はすべてのマウス移動を追跡するアプリにのみ届きます。
+
+`terminal session observe` は同じ対象の読み取り専用ストリームを開きます。base64 の ANSI バイト列を含む `terminal.frame` と、サーバー終了時の `terminal.closed` を改行区切り JSON で出力します。複数の観測クライアントは入力、リサイズ、スクロール、制御権を取得せずに同じターミナルを監視できます。Linux/macOS ではソケットへの書き込みが 30 秒間進まない観測クライアントを切断します。その場合は最後の `terminal.closed` が届かないことがありますが、ペインや他のクライアントは動き続けます。出力のない静かなペインはこのタイムアウトの対象ではありません。
+
+`terminal title clear` は外側ターミナルウィンドウタイトルを `ui.window_title` に戻します。
+
+## 出力待機
+
+ペインの出力を待つ:
+
+```bash
+herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--raw]
+```
+
+通常のコマンドやサーバーには `pane wait-output` を使います。コーディングエージェントには `agent wait` を使います。
+
+`pane wait-output` は選択したスナップショットを最初にすぐ検索するため、すでに存在する出力も一致します。デフォルトのソース名は `recent` で、直近 80 行の描画済みターミナル行を折り返し前の出力として扱います。`--lines` でその行数を変更できます。`--match` は 1 行内のリテラル部分文字列を検索し、`--regex` は Rust の正規表現構文で 1 行ずつ一致します。
+
+タイムアウトや `agent_prompt_stalled` は未送信を保証しません。再試行前にエージェントを確認してください。
+
+`pane wait-output` と `agent wait` は、`--timeout` を省略すると無期限に待ちます。`agent prompt --wait` では、活動を観測した後、またはプロンプト開始時に `working` だった場合の安定状態待機は無期限です。non-working 状態から開始して活動を観測できない場合は、5 秒後に `agent_prompt_stalled` を返します。タイムアウトまたはサーバーエラーは JSON として stderr に出力され、終了コード 1 になります。CLI 使用法のエラーは終了コード 2 です。
+
+## インテグレーション
+
+```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 mastracode
+herdr integration install qodercli
+herdr integration install qwen
+herdr integration install letta
+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 mastracode
+herdr integration uninstall qodercli
+herdr integration uninstall qwen
+herdr integration uninstall letta
+herdr integration uninstall cursor
+herdr integration status [--outdated-only]
+```
+
+## プラグイン
+
+プラグインコマンドは、ローカル実行型ワークフロープラグインをインストールして実行します。プラグインはマニフェストとプロセス外コマンドの組み合わせです。ホスト側の面は Herdr が、実装言語はプラグインが担います。
+
+プラグインのインストール、一覧、削除:
+
+```bash
+herdr plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]
+herdr plugin update [<plugin_id|owner/repo[/subdir...]>...] [--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` を使ってください。`plugin update` は対象を省略すると GitHub 管理の全プラグインを、指定すると該当する id または GitHub ソースだけを更新します。記録された ref を使い、変更のないコミットと一括更新時のローカルリンクをスキップします。再インストールは新しいディレクトリを作成します。実行中のプラグインは元のファイルを、新しい呼び出しは新しい版を使います。ローカルにリンクされたプラグインへの上書きインストールは拒否されます。プラグインのマニフェストは `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` は登録を解除し、実行中のプラグインが完了できるようファイルを残します。更新や再インストールも古い版を保持し、新しい呼び出しは設定の再読み込みなしで新しい版を使います。使用中のサーバーが終了した後、次に成功したインストール／更新、またはサーバー起動時に不要な管理インストールを削除します。設定の再読み込みでは解放されません。プラグインは親コマンドやペインの終了前に、切り離したバックグラウンドプロセスを停止する必要があります。サーバー終了後も残るプロセスは削除から保護されません。削除追跡のない旧インストールとローカルリンクのファイルは保持します。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|popup|split|tab|zoomed] [--width SIZE] [--height SIZE] [--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` で、アクティブなペインの上に一時的なズームオーバーレイを開きます。分割、新しいタブ、ズームされたペイン、またはタブレイアウトを変更しないセッションモーダルな `popup` として開くこともできます。`--width` と `--height` は、外側のポップアップ寸法をターミナルセル数または `80%` のような割合で指定します。省略した寸法はデフォルトでターミナルの半分になり、小さすぎる値はポップアップの最小サイズに制限されます。ポップアップは Herdr ペインではなく、`HERDR_PANE_ID` を受け取らず、pane API やエージェント API に参加しません。ターミナル以外のネイティブなプラグインペインは今後の対応面です。
+
+新しいペインでは `TERM_PROGRAM=herdr` として識別され、`TERM_PROGRAM_VERSION` には Herdr のバージョンが設定されます。`TERM=xterm-256color` と `COLORTERM=truecolor` は維持されます。リサイズ時に Herdr がテキストを折り返し直すため、`fish_handle_reflow=0` も設定します。継承した値や明示的な `fish_handle_reflow` の指定は優先されます。Herdr は、明示的な起動環境の値を適用する前に、継承した外側のターミナルのセッションマーカー（iTerm2、WezTerm、Kitty、Windows Terminal、tmux、screen、Zellij）、iTerm2 の `LC_TERMINAL` 識別子、既知の Claude Code、Codex、OMP セッションマーカーを削除します。これにより、新しいペインがサーバーを最初に起動したターミナルやエージェントのセッションを名乗ることを防ぎます。API キーやディスプレイ設定を含む通常の環境変数は、アタッチ中クライアントの環境に置き換えられず、引き続き継承されます。SSH エージェント転送には独自の再接続処理があります。このクリーンアップによって既存ペインのプロセスは変更されません。
+
+`--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` | エージェントのスクリーン検出が使う下部バッファのスナップショット。 |
+
+この表は読み取り時の意味です。`pane wait-output` に限り、`recent` と `recent-unwrapped` はどちらも recent の折り返し前スナップショットを検索し、デフォルト表記は `recent` です。
+
+## 環境変数
+
+| 変数 | 目的 |
+| --- | --- |
+| `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` | サウンド通知が有効でも音の再生を無効にする。 |
@@ -0,0 +1,89 @@
+---
+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 が状態を確信を持って分類できない。 |
+
+各クライアントは表示した完了を独立して管理します。あるクライアントで完了を見ても、ほかのクライアントの Done バッジは消えません。CLI/API はサーバーの既読状態を使うため、特定のクライアントのバッジと一致するとは限りません。`idle` と `done` はどちらも入力可能な状態です。
+
+## セッション
+
+セッションは永続的な Herdr サーバーの名前空間です。デフォルトの `herdr` コマンドはデフォルトセッションにアタッチします。
+
+名前付きセッションは独立したランタイム名前空間です:
+
+```bash
+herdr session list
+herdr session attach work
+herdr session attach side-project
+```
+
+まずはワークスペースを使ってください。ペイン、ソケット、永続化されたランタイム状態を完全に分離する必要があるときに名前付きセッションを使います。
+
+## クライアントとサーバー
+
+デフォルトでは、Herdr はバックグラウンドサーバーと、それにアタッチした 1 つ以上のクライアントとして動作します。
+
+サーバーはペインとプロセス状態を所有します。クライアントはそのサーバーにアタッチしたターミナル UI です。
+
+クライアントが 1 つだけ接続されている場合、従来どおりすべてのタブがそのサイズに従います。複数のクライアントが接続されている場合、それぞれ別のワークスペースやタブを表示できます。異なるタブはそれぞれを表示するクライアントのサイズに従い、同じタブを表示している場合は、最後にそのタブへフォーカス、選択、または操作したクライアントがペインのサイズを制御します。
+
+`ctrl+b q` でクライアントをデタッチします。サーバーとエージェントは動き続けます。
+
+セッションを終了してそのペインを停止したい場合は、サーバーを停止します:
+
+```bash
+herdr server stop
+```
+
+## モード
+
+Herdr にはターミナルモード、プレフィックスモード、ナビゲートモードがあります。
+
+ターミナルモードはフォーカス中のペインにキーを送ります。プレフィックスモードはプレフィックスキーの後に Herdr のアクションをひとつ待ちます。ナビゲートモードは常駐のワークスペースナビゲーション画面です。
+
+プレフィックスキー (デフォルト `ctrl+b`) を押してから、新しいタブなら `c`、ワークスペースナビゲーションなら `w` のようにアクションキーを押します。プレフィックスの考え方が初めてなら[キーボード](/ja/docs/keyboard/)を参照してください。
@@ -0,0 +1,27 @@
+---
+title: 設定リファレンス
+description: Herdr の正規の config.toml キーを、型・デフォルト値・許容値つきで一覧します。
+---
+
+import ConfigReference from '../../../components/ConfigReference.astro';
+
+Herdr が `config.toml` から読み取る正規キーを、フラットに一覧して絞り込めます。
+ガイド付きの設定手順や各オプションの背景は[設定](/ja/docs/configuration/)を参照してください。
+
+コメント付きのデフォルト設定全体はいつでも出力できます:
+
+```bash
+herdr --default-config
+```
+
+カスタムコマンドバインディング（`[[keys.command]]`）はユーザー定義のテーブルのため、
+ここではキーごとに掲載していません。
+[カスタムコマンドキーバインド](/ja/docs/configuration/#カスタムコマンドキーバインド)を参照してください。
+
+各キーの説明は現時点では英語です。
+
+<ConfigReference
+  placeholder="キーを絞り込み（例: sidebar, prefix, sound…）"
+  noMatches="一致するキーはありません。"
+  keyCountLabel="キー"
+/>
@@ -0,0 +1,610 @@
+---
+title: 設定
+description: Herdr のキーバインド、テーマ、サイドバーの挙動、通知、高度なオプションを設定します。
+---
+
+Herdr は設定ファイルなしで動作します。キー、テーマ、サイドバーのレイアウト、通知、高度な挙動をカスタマイズしたい場合に追加してください。
+
+設定やキーバインドを探していますか？すべてのキー、型、デフォルト値、許容値は[設定リファレンス](/docs/config-reference/)で検索できます。このページでは、セットアップ、一般的なレシピ、リファレンスの一行だけでは説明しきれない設定構造を中心に説明します。
+
+## 設定ファイル
+
+Herdr は次の場所から設定を読み込みます:
+
+```text
+Linux and macOS: ~/.config/herdr/config.toml
+Windows:          %APPDATA%\herdr\config.toml
+```
+
+システム上で解決された設定ファイルのパスは、`herdr --help` で確認できます。
+
+完全なデフォルト設定を表示します:
+
+```bash
+herdr --default-config
+```
+
+完全な出発点が欲しい場合は、これを設定として保存してください:
+
+```bash
+herdr --default-config > ~/.config/herdr/config.toml
+```
+
+設定値が無効な場合、Herdr は安全なデフォルト値にフォールバックし、起動時に警告を表示します。
+
+`onboarding` が存在しないか true の場合、Herdr は初回セットアップを表示します。オンボーディングから先へ進むと `onboarding = false` が書き込まれ、設定のインテグレーションタブが開きます。セットアップ後にこのフローをスキップしたい場合に設定してください。
+
+```toml
+onboarding = false
+```
+
+## 設定のリロード
+
+`config.toml` を編集した後、実行中のサーバーをリロードします:
+
+```bash
+herdr server reload-config
+```
+
+Herdr のグローバルメニューを開いて `reload config` を選ぶこともできます。
+
+リロードは、ペインを再起動せずにほとんどの UI 設定を適用します。起動時のみの設定には引き続き再起動が必要です。
+
+テーマ、サイドバーのレイアウト、コピー動作などの表示設定は、SSH マシンを表示している場合もクライアントのローカル設定から読み込みます。ペインのデフォルト、worktree、インテグレーション、カスタムコマンドは、ペインが動くサーバー側の設定です。UI の `reload config` は、クライアントのローカル設定と選択中サーバーの設定を両方リロードします。ローカルキーバインドも反映されます。`--remote-keybindings server` を指定した場合は、選択中サーバーのキーバインドを使います。
+
+## ヘッドレスターミナルのサイズ
+
+クライアントが接続されていない場合、サーバーはレイアウトと新しく作成されるペインに 120×40 の仮想ターミナルを使います。ヘッドレスオーケストレーション用のフォールバックは次のように変更できます:
+
+```toml
+[server]
+headless_cols = 160
+headless_rows = 50
+```
+
+クライアントが 1 つだけ接続されている場合、すべてのタブがそのサイズに従います。複数のクライアントが接続されている場合、表示中の各タブは、最後にそのタブへフォーカス、選択、または操作したクライアントのサイズに従います。1 つを除くすべてのクライアントが切断すると、すべてのタブは残ったクライアントのサイズへすぐに戻ります。クライアントが 1 つも残っていない場合、既存のペイン PTY は最後のサイズを保ち、新しいヘッドレスレイアウトには設定したフォールバックが使われます。
+
+## ターミナルのデフォルト
+
+新しく作成される対話型ペインに Herdr が使う実行ファイルを設定します:
+
+```toml
+[terminal]
+default_shell = "nu"
+```
+
+未設定または空の場合、Herdr は Unix では `$SHELL`、次に `/bin/sh` を使います。Windows では、`PATH` 上で解決できる場合は `pwsh.exe`（PowerShell 7）を使い、それ以外は標準搭載の `powershell.exe`（Windows PowerShell 5.1）を使います。これは実行ファイル名またはパスであり、シェルのコマンドラインではありません。既存のペインは再作成されるまで現在のシェルを保ちます。カスタムコマンドキーバインドの文字列は、Unix ではペインコマンドに `/bin/sh -c`、デタッチコマンドに `/bin/sh -lc` を通して実行され、Windows では `cmd.exe /d /c` を通して実行されます。
+
+新しく作成される対話型ペインのシェルの起動方法を設定します:
+
+```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 設定を取り込み、その後にフォールバックの `ServerAliveInterval` と `ServerAliveCountMax` の値を加えた、プライベートな一時 SSH 設定を書き込みます。ユーザー自身のキープアライブ設定が優先されます。Linux と macOS クライアントは、最初に認証した接続を再利用するため、アタッチごとにプライベートな OpenSSH コントロールソケットも使います。Windows OpenSSH ではこの接続再利用を使いません。Herdr が生成した設定やコントロールソケットを使わず、通常の `ssh` でリモートアタッチを実行するには `manage_ssh_config = false` を設定してください。
+
+## キーバインド
+
+プレフィックスの導入ガイドと検証済みのプレフィックスなし構成については、[キーボード](/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"
+```
+
+`keys.prefix` は、複数のキーからプレフィックスモードに入りたい場合には配列も受け付けます。たとえば、macOS とリモート Linux マシンで 1 つの設定を共有できます:
+
+```toml
+[keys]
+prefix = ["ctrl+space", "ctrl+s"]
+```
+
+設定したどのプレフィックスでも同じプレフィックスモードに入り、すべての `prefix+...` アクションを開始できます。最初の項目がステータスバーに表示されるプライマリプレフィックスとなり、`prefix+?` のアプリ内ヘルプパネルにはすべてのプレフィックスが表示されます。
+
+デフォルトのキーマップはプレフィックス優先なので、Herdr がシェル、エディタ、tmux、ターミナルアプリから入力を奪うことはありません。[設定リファレンス](/docs/config-reference/)で `keys.` を検索すると、すべてのアクションとデフォルトのバインドを確認できます。`prefix+?` で開くアプリ内ヘルプパネルには、現在有効なバインドが表示されます。
+
+1 つのアクションに複数のショートカットが必要な場合、バインドを配列にすることもできます:
+
+```toml
+[keys]
+next_tab = ["prefix+n", "ctrl+alt+]"]
+```
+
+任意のアクションはデフォルトでは未設定です。プレフィックスモードの挙動には `prefix+` でバインドし、意図的に直接ショートカットにする場合は明示的な修飾キーコードを使ってください。たとえば、リサイズモードに入らず tmux のように 1 回のキー操作でペインをリサイズできます:
+
+```toml
+[keys]
+resize_pane_left = "ctrl+shift+alt+left"
+resize_pane_down = "ctrl+shift+alt+down"
+resize_pane_up = "ctrl+shift+alt+up"
+resize_pane_right = "ctrl+shift+alt+right"
+```
+
+キー文字列には、通常のキー、`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 = "popup"
+command = "lazygit"
+description = "run lazygit"
+width = "80%"
+height = "80%"
+```
+
+`type = "popup"` は、タブレイアウトを変更せずにセッションモーダルなポップアップを開きます。
+ポップアップは、コマンドが終了するまで Escape を含むすべてのターミナル入力を受け取ります。
+`width` と `height` は任意です。省略するとデフォルトの半分のサイズになり、数値ならターミナルセル数、`"80%"` のような文字列ならターミナル領域に対する割合を指定できます。
+寸法にはポップアップの枠が含まれ、小さすぎる値は最小サイズに制限されます。
+ポップアップコマンドは `HERDR_PANE_ID` を受け取りません。背後のタイルペインには `HERDR_ACTIVE_PANE_ID` を使ってください。
+
+Unix と macOS では、分割やタブを追加せずに一時的なターミナルを開くこともできます:
+
+```toml
+[[keys.command]]
+key = "prefix+t"
+type = "popup"
+command = "exec \"${SHELL:-sh}\""
+description = "open scratch terminal"
+width = "80%"
+height = "80%"
+```
+
+Windows では、代わりに `command = "powershell.exe -NoLogo"` のようなシェルコマンドを使ってください。
+シェルを終了するとポップアップが閉じ、タイル表示に戻ります。
+
+`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 が検出できる場合、シェルコマンドはフォーカス中のペインの作業ディレクトリから実行されます。
+
+Windows では、カスタムコマンド文字列に `cmd.exe /d /c` が使われるため、環境変数には `%HERDR_BIN_PATH%` 構文を使います。PowerShell 構文を実行するには、たとえば `powershell.exe -NoProfile -Command "..."` のように明示的に呼び出してください。
+
+## テーマ
+
+組み込みテーマを選びます:
+
+```toml
+[theme]
+name = "catppuccin"
+```
+
+すべての組み込みテーマは、[設定リファレンス](/docs/config-reference/)で `theme.name` を検索してください。Herdr の UI 色をホストターミナルの ANSI パレットに従わせたいときは `terminal` を使ってください。
+
+Unix では、リサイズまたは `SIGWINCH` 後の再描画時にも、Herdr はホストターミナルの色を再読み込みします。テーマ切り替えツールがライト/ダーク通知を送らずに OSC でターミナル色を変更する場合は、新しいパレットを適用した後に `kill -WINCH <client-pid>` を送ってください。サーバーではなく、アタッチ中の Herdr クライアントを対象にします。既存のペインは動作し続けます。直接の `herdr terminal attach` セッションでは、パレットの問い合わせはアタッチ先アプリケーションに委ねられます。
+
+ホストターミナルがライト/ダークの外観変更を報告したときに、Herdr が自身の UI テーマを切り替えるようにするには、テーマの自動切り替えを有効にします:
+
+```toml
+[theme]
+name = "catppuccin"
+auto_switch = true
+light_name = "catppuccin-latte"
+dark_name = "catppuccin"
+```
+
+`auto_switch` のデフォルトは `false` なので、既存のテーマ設定は手動の挙動を保ちます。`light_name` または `dark_name` を省略すると、設定された `name` に対応する組み込みの姉妹テーマが存在する場合はそれを使います。たとえば `tokyo-night`/`tokyo-night-day` や `gruvbox`/`gruvbox-light` です。設定画面でテーマを手動選択すると `auto_switch` は無効になります。
+
+個々の色を上書きできます:
+
+```toml
+[theme.custom]
+sidebar_bg = "#181825"
+active_row_bg = "#1e1e2e"
+selection_bg = "#313244"
+panel_bg = "reset"
+accent = "#a6e3a1"
+green = "#a6e3a1"
+blue = "#89b4fa"
+red = "#f38ba8"
+yellow = "#f9e2af"
+```
+
+`sidebar_bg` を使うと、デスクトップのサイドバーだけに背景色を設定できます。省略した場合、サイドバーはホストターミナルの背景を使います。`active_row_bg` は、区切り線やスクロールバートラックに影響を与えず、アクティブな Space とフォーカス中の Agent 行の背景色を変更します。`selection_bg` は、サイドバーの Navigate モードのカーソル行の背景色を変更します。
+
+色の値には、hex、名前付きの色、`rgb(r,g,b)`、または `reset`、`default`、`none`、`transparent` のようなリセットエイリアスが使えます。
+
+`auto_switch` が有効な場合は、ライト/ダーク別のサブテーブルを共有カスタム色の上に重ねられます:
+
+```toml
+[theme.custom]
+accent = "#89b4fa"
+
+[theme.custom.light]
+panel_bg = "#eff1f5"
+text = "#4c4f69"
+
+[theme.custom.dark]
+panel_bg = "#1e1e2e"
+text = "#cdd6f4"
+```
+
+有効なパレットには、組み込みテーマ、`[theme.custom]`、`[theme.custom.light]` または `[theme.custom.dark]` の順で適用されます。モード別のサブテーブルを省略すると、既存の共有上書きの挙動が維持されます。
+
+## UI とサイドバー
+
+サイドバーは Herdr のメインダッシュボードです。サイズ、折りたたみモード、Agent パネルの並び順、マウスの挙動、ペインの境界線、その他の表示設定については、[設定リファレンス](/docs/config-reference/)で `ui.` を検索してください。
+
+`ui.pane_borders` は `"auto"`（デフォルト。分割ペインだけに境界線を表示）、`"always"`（単独ペインにも枠を表示）、`"off"` を受け付けます。単独ペインの辺はすべて外側の辺なので、枠を表示するには `ui.pane_outer_borders = true` も必要です。従来の真偽値も有効で、`true` は `"auto"`、`false` は `"off"` に対応します。
+
+`[ui]` の `tab_bar_position = "bottom"` を設定すると、デスクトップのタブ行をターミナルペインの下に配置できます。Prefix、Navigate、Copy、Resize の各モードバーは、表示中だけ下部のタブ行を置き換えます。デフォルトは `"top"` です。
+
+タブ行の右端に、tmux のような順序付きステータス領域を設定できます:
+
+```toml
+[ui]
+tab_bar_right = [
+  { type = "zoom" },
+  { type = "hostname" },
+  { type = "datetime", format = "%H:%M" },
+  { type = "text", text = "prod" },
+  { type = "command", command = "~/.config/herdr/status.sh", interval_seconds = 5, timeout_seconds = 2 },
+]
+tab_bar_right_separator = " · "
+```
+
+ステータス領域はデフォルトでは空です。`zoom` を追加すると、アクティブなタブがズーム中のとき固定の `ZOOM` ピルが表示されます。各タブの既存の `Z` マーカーとは独立しています。`hostname`、`datetime`、`command` は Herdr サーバー上で解決されるため、`herdr --remote` ではリモートマシンの値が表示されます。日時エントリは `strftime` 形式を使います。`%z` や `%s` のように UTC オフセットまたは Unix タイムスタンプを必要とする指定子は、値がサーバーローカルの壁時計時刻であるため拒否されます。
+
+コマンドエントリはすぐに実行され、その後 `interval_seconds` ごとに更新されます。描画をブロックせず、前回の実行と重複しません。間隔は 1〜31,536,000 秒、タイムアウトは 1〜3,600 秒です。Herdr は成功した出力の最終行を使い、ESC で始まるターミナル制御シーケンスは装飾として解釈せずに除去します。失敗、空の出力、`timeout_seconds` 経過後には値を消去します。カスタムコマンドキーバインドと同じアクティブなワークスペース、タブ、ペイン、ソケット、バイナリ、作業ディレクトリのコンテキストが提供されます。コマンドは Linux、macOS、Windows で利用でき、Linux と macOS では `/bin/sh -lc`、Windows では `cmd.exe /d /c` が使われます。
+
+区切り文字は、表示されているエントリの間にだけ挿入されます。直接連結するには `tab_bar_right_separator = ""` を設定します。タブ行が狭い場合、ステータス領域全体がタブとそのコントロールに場所を譲ります。
+
+### 外側のターミナルのウィンドウタイトル
+
+Herdr はペイン内のターミナルをエミュレートするため、ペイン内で書き込まれた `OSC 0`/`OSC 2` のタイトルは Herdr で止まります。Herdr は自身が動作しているターミナルに独自のタイトルを書き込み、ウィンドウマネージャーやターミナルのタブバーはこれを読み取ります:
+
+```toml
+[ui]
+window_title = "{hostname}: {workspace}"
+```
+
+トークンは `{hostname}`、`{workspace}`、`{tab}`、`{pane}`(フォーカス中のペインの手動名)、`{terminal_title}`(フォーカス中のペイン自身のターミナルタイトルからスピナーを取り除いたもの)です。波括弧そのものを書くには `{{` と `}}` を使います。値のないトークンは空になります。
+
+タイトルは Herdr サーバー上で生成されるため、`herdr --remote` で接続した場合や SSH 越しに `herdr` を実行した場合でも、`{hostname}` はペインが動作しているマシンを指します。外側のターミナルのタイトルに触れないようにするには `window_title = ""` を設定します。
+
+`client.window_title.set` は設定されたタイトルを上書きし、`client.window_title.clear` がそれを戻します。
+
+Agent の状態は、デフォルトではコンパクトな色付きドットで表示されます。blocked、working、done、idle、unknown を色だけでなく形でも区別するには、設定画面で **distinct symbols** を選ぶか、次のように設定します:
+
+```toml
+[ui]
+status_indicators = "symbols"
+```
+
+これらの記号は静的なので、このオプションでスピナーアニメーションが有効になることはありません。
+
+### サイドバーの行レイアウト
+
+展開されたデスクトップサイドバーでは、`rows` の各内側の配列が 1 行として描画されます。完全なデフォルトレイアウトは次のとおりです:
+
+```toml
+[ui.sidebar.agents]
+row_gap = 0
+rows = [
+  ["state_icon", "machine", "workspace", "tab"],
+  ["agent"],
+]
+
+[ui.sidebar.spaces]
+row_gap = 0
+rows = [
+  ["state_icon", "workspace"],
+  ["branch", "git_status"],
+]
+```
+
+Agent の行では、次の組み込みトークンを使えます:
+
+- `state_icon` — エージェントの意味的な状態を示す色付きアイコン。
+- `state_text` — `idle`、`working`、`blocked`、`done`、`unknown`。報告された表示ラベルがある場合はそれも含みます。
+- `machine` — クライアントに複数のマシンがある場合のマシンラベル。ローカルマシン 1 台だけの場合は省略されます。
+- `workspace` — ワークスペース名。
+- `tab` — 利用可能な場合はタブ名。
+- `pane` — 利用可能な場合はペイン名。
+- `agent` — 検出または報告されたエージェントの表示名。
+- `terminal_title` — 安全性のための正規化後の最新の OSC 0/2 ターミナルタイトル。
+- `terminal_title_stripped` — 認識された先頭のアクティビティまたはスピナーのグリフ 1 つと、それに続く空白を除去したターミナルタイトル。
+- `$name` — `name` という名前のカスタムペインメタデータ。
+
+Space の行では、次の組み込みトークンを使えます:
+
+- `state_icon` — Space 内で集約されたエージェント状態を示す色付きアイコン。
+- `state_text` — Space 内で集約されたエージェント状態のテキスト。
+- `workspace` — ワークスペース名。
+- `branch` — 利用可能な場合は Git ブランチ。
+- `git_status` — 0 でない場合は Git の ahead と behind の件数。
+- `$name` — `name` という名前のカスタムワークスペースメタデータ。
+
+トークンは設定された順序で描画されます。Herdr は通常、隣接する値を ` · ` で区切り、`state_icon` の後には空白を 1 つ入れます。値がない場合、その値と区切りは表示されません。すべてのトークンに値がない行は表示されません。既存のカスタム行は変更されません。カスタムの複数マシンレイアウトでマシンを識別したい場合は、`machine` を明示的に追加してください。各レイアウトは最大 16 行、各行は最大 16 トークンです。
+
+トークンエントリにはインラインのスタイルテーブルも使えます:
+
+```toml
+[ui.sidebar.agents]
+rows = [
+  ["state_icon", { token = "workspace", bold = false }, "tab"],
+  [{ token = "$summary", fg = "#89b4fa", bold = true, dim = false }],
+]
+```
+
+`fg` は厳密な `#RGB` または `#RRGGBB`、`bold` と `dim` は真偽値です。省略したフィールドはコンテキストのスタイルを保持し、明示的な `false` はその修飾を解除します。スタイルは 1 つの出現箇所だけに適用されます。`fg` を指定した `git_status` では、既定の緑/赤ではなく ahead と behind の両方が同じ色になります。区切りと行の背景は変更されません。
+
+テキスト値のトークンには、順序付きの `rules` を最大 16 個指定できます。各ルールには `equals`、`contains`、`starts_with`、`gt`、`lt` のいずれか 1 つの条件と、任意の `fg`、`bold`、`dim` 上書きを指定します:
+
+```toml
+[ui.sidebar.agents]
+rows = [
+  ["state_icon", "workspace", "tab"],
+  [{ token = "machine", fg = "#fff", rules = [{ equals = "Local", fg = "#f55" }, { equals = "Fedora", ignore_case = true, fg = "#51a2da" }] }, "agent"],
+  [{ token = "$load", fg = "#fff", rules = [{ gt = 80, fg = "#f55", bold = true }, { gt = 50, fg = "#fc0" }] }],
+]
+```
+
+最初に一致したルールだけを適用します。指定されたスタイルはその出現箇所のデフォルトを上書きし、省略したフィールドは継承します。一致しなければデフォルトを保ちます。判定には表示幅で切り詰める前の値全体を使います。ルールに `hide = true` を指定すると、一致したトークンとその区切りを非表示にします。残るトークンがない行も非表示になります。たとえば `{ token = "machine", fg = "#61afef", rules = [{ equals = "Local", hide = true }] }` は、ラベルが正確に `Local` の場合にマシントークンを非表示にします。接続の種類ではなくラベルを比較します。`hide = false` または省略時は表示を維持します。上書きを指定しないルールでも、一致するとそこで判定を終了してデフォルトを保ちます。
+
+`equals`、`contains`、`starts_with` は文字列を受け取り、大文字と小文字を区別します。`ignore_case = true` は ASCII だけを区別しなくなり、非 ASCII 文字は引き続き区別します。空文字列の `equals` は空の値だけに一致し、空の `contains` と `starts_with` は存在するすべての値に一致します。
+
+`gt` と `lt` は有限の数値を閾値とし、等しい値は含みません。値全体が有限の数値として解析できる必要があり、小数と指数表記は使えますが、空白、単位、`NaN`、無限大は一致しません。数値ルールに `ignore_case` は指定できません。比較は浮動小数点で行い、大きな整数の厳密な比較には使えません。
+
+ルールは Agent 行、`rows_by_agent` の上書き、Space 行のテキスト値の組み込みトークンとカスタム `$name` トークンに使えます。上の例では `$load` が `"90"` なら赤の太字、`"60"` なら黄色、`"90%"` なら白のままです。未報告のトークンは表示されません。`state_icon` と複合トークン `git_status` は固定スタイルだけを受け付け、ルールは使えません。不明な条件や不正なルールは設定読み込み時に拒否します。正規表現、あいまい一致、スクリプトには対応しません。
+
+`row_gap` は、Agent パネルと Space パネルごとに、エントリ間の空白行数を指定します。デフォルトは `0` で、エントリを詰めて表示します。以前の間隔に戻すには `1` に設定します。`rows` で定義したコンテンツ行の間隔には影響しません。連続するインデントされた worktree の子は、1 つの Space グループとして詰めて表示されます。
+
+既知のエージェントについて Agent の完全なレイアウトを上書きするには、`rows_by_agent` を使います:
+
+```toml
+[ui.sidebar.agents]
+rows = [
+  ["state_icon", "agent", "state_text"],
+  ["workspace", "tab"],
+]
+
+[ui.sidebar.agents.rows_by_agent]
+claude = [
+  ["state_icon", "agent", "state_text"],
+  ["terminal_title_stripped"],
+  ["workspace", "tab"],
+]
+```
+
+上書きは `rows` を置き換えるもので、拡張するものではありません。上書きのキーには、`claude`、`codex`、`pi` のような大文字と小文字を区別する正規エージェント ID を使います。`claude-code` のような検出エイリアスは使えません。カスタム報告されたエージェントを含め、上書きがないエージェントには `rows` が使われます。
+
+カスタム `$name` トークンは動的な値であり、リテラルテキストではありません。トークンをレイアウトに追加してから、スクリプトまたはプラグインで値を報告します:
+
+```toml
+[ui.sidebar.agents]
+rows = [
+  ["state_icon", "agent", "$model"],
+  ["$summary"],
+  ["workspace", "tab"],
+]
+```
+
+```bash
+herdr pane report-metadata <pane_id> \
+  --source my-agent-hook \
+  --token model=opus \
+  --token summary="reviewing authentication"
+```
+
+カスタム Space トークンには、同じ方法で `herdr workspace report-metadata` を使います。報告されていないカスタムトークンは表示されません。
+
+メタデータの報告元が提供できるのは値だけで、スタイルはローカルのサイドバー設定で管理します。上限、クリア、シーケンス、有効期限については、[CLI リファレンス: report metadata](/docs/cli-reference/#panes)を参照してください。
+
+サイドバーの行設定は、展開されたデスクトップサイドバーにだけ適用されます。折りたたみ表示とモバイル表示はコンパクトなレイアウトを保ちます。
+
+## 通知
+
+Herdr は、バックグラウンドのエージェントが完了したり入力を必要としたりしたときに通知できます:
+
+```toml
+[ui.toast]
+delivery = "herdr"
+delay_seconds = 1
+
+[ui.toast.herdr]
+position = "bottom-right"
+```
+
+アプリ内トーストには `herdr`、SSH 越しでも使いやすい外側のターミナル通知には `terminal`、ローカル OS の通知サービスには `system`、ポップアップを無効にするには `off` を選びます。Herdr はアクティブなタブのポップアップを抑制します。位置、遅延の挙動、クリップボードのフィードバック設定については、[設定リファレンス](/docs/config-reference/)で `ui.toast` を検索してください。
+
+macOS では、`system` は最初に `terminal-notifier` を試し、利用できない場合や失敗した場合は `/usr/bin/osascript` にフォールバックします。このフォールバックは通知センターで Script Editor として表示され、ホストターミナルをアクティブにできません。`brew install terminal-notifier` で `terminal-notifier` をインストールできます。対応するターミナルを Herdr が検出できた場合、通知のクリック時にそのターミナルアプリをアクティブにできます。または、`terminal` を選んで対応する外側のターミナルに通知を送信させてください。
+
+Windows の `system` 通知は通知センターに残ります。クリックすると、実行中の Herdr クライアントで元のペインを選択し、Windows が対象ウィンドウを取得できればターミナルを前面に出します。閉じたクライアントを開き直したり、再起動したサーバーのペインを選択したりはできません。Windows Terminal ではウィンドウを前面に出せますが、外側の別タブを確実に選択することはできません。
+
+## サウンド
+
+サウンド通知はローカルの Herdr クライアントで再生されます。カスタムサウンドは mp3 ファイルでなければなりません。相対パスは設定ファイルのディレクトリから解決されます。
+
+```toml
+[ui.sound]
+path = "sounds/notification.mp3"
+done_path = "sounds/done.mp3"
+request_path = "sounds/request.mp3"
+```
+
+`path` はすべてのサウンド通知に 1 つの音を設定します。`done_path` と `request_path` は、完了音と入力要求音だけを上書きします。
+
+エージェント別のサウンド上書きには `default`、`on`、`off` を指定できます。キーには `claude`、`codex`、`devin`、`droid` のような検出されたエージェントラベルを使います。Droid はデフォルトでミュートされています。
+
+```toml
+[ui.sound.agents]
+droid = "off"
+claude = "on"
+```
+
+## 高度な設定
+
+スクロールバックの上限、ネストされた起動、その他の高度な設定や実験的設定については、[設定リファレンス](/docs/config-reference/)を検索してください。ペイン画面履歴を有効にする前に、[セッション状態と復元](/docs/session-state/)を参照してください。このガイドでは、ペインの内容を保存する場合のセキュリティ上のトレードオフを説明しています。
+
+## Kitty graphics
+
+アプリケーションとプラグインは、ペインのターミナル出力に送られる標準の Kitty graphics プロトコルを通じて統合します。Herdr は、対応する外側のターミナルでこれらの画像をデフォルトで描画します。外部ソケットのペインオーバーレイ API は削除され、代替となるソケット画像 API はありません。
+
+ポップアップ、メニュー、通知は、覆う領域に合わせて画像を切り抜きます。各画像の残りは表示されたままで、覆われた部分はオーバーレイが閉じると戻ります。画像はダイアログの背景と一緒に暗くなりません。
+
+Herdr は、アプリケーションの変更や環境変数による切り替えなしで、利用可能なファイル転送方式を自動的に選びます。ローカル Unix の Ghostty クライアントでは、画像データをターミナル出力へエンコードする代わりに、一時ファイル経由で送信できます。最初に小さなファイル読み取りプローブで対応状況を確認します。その他のターミナル、SSH で起動したクライアント、ネストしたマルチプレクサーでは、この最終区間の最適化にインライン出力を使い続けます。
+
+対象となるローカルクライアントでは、ネイティブ RGBA 画像はピクセルバイトではなく、Herdr が所有するスナップショットへのパスとしてサーバーからクライアントへ送られます。未対応のクライアントや失敗した転送はインライン配信にフォールバックします。リモートサーバーのパスがローカルターミナルへ転送されることはありません。画像の配置、クリッピング、可視性は Herdr が管理します。
+
+Linux では、ファイル全体を使う非圧縮 RGBA アップロードについて、Herdr がピクセルを読み取る前にコピーオンライトのスナップショットを作成できます。これには、Herdr 専用の `/var/tmp` ストアへのクローンをファイルシステムがサポートしている必要があります。未対応のファイルシステム、一時ファイルのアップロード、共有メモリ、その他の形式では通常のローダーを使います。スナップショットは 1 個あたり 16 MiB、合計 64 MiB に制限されます。アニメーションと未対応クライアントでは、必要な時点でピクセルを読み取ります。Herdr は画像を受理した後、変更可能な生成元パスに依存しません。
+
+PNG アップロードでは完全なデコードと検証を引き続き行います。破損画像の検証を外側のターミナルへ先送りすることはありません。
+
+Kitty graphics の描画を無効にするには、次のように設定します:
+
+```toml
+[terminal]
+kitty_graphics = false
+```
+
+既存の設定との互換性のため、従来の `experimental.kitty_graphics` 設定も引き続き使用できます。両方が設定されている場合は、`terminal.kitty_graphics` が優先されます。
+
+この設定を変更した場合は、対象の Herdr サーバーを再起動するか、クライアントを再アタッチする必要があります。リモートセッションでは、サーバー側の設定が Kitty graphics の解析を制御し、ローカルクライアント側の設定が外側のターミナルへの出力を制御します。
+
+## Agent セッション復元
+
+Herdr はデフォルトで、サーバーの再起動後に対応する Agent の会話を再開します:
+
+```toml
+[session]
+resume_agents_on_restore = true
+startup_per_agent_delay_ms = 100
+```
+
+起動時の競合を減らすため、自動復元ではデフォルトで 100 ミリ秒間隔でエージェントを 1 つずつ起動します。起動条件を満たした最初のエージェントはすぐに起動します。`startup_per_agent_delay_ms = 0` で間隔を無効にできます。手動起動と明示的なターミナルへの接続には影響しません。変更を適用するには Herdr サーバーを再起動してください。
+
+公式インテグレーションからの有効なネイティブセッション参照を持つペインだけが再開できます。その他のペインは通常のシェルとして復元されます。対応する Agent と永続化の挙動については、[セッション状態と復元](/docs/session-state/)を参照してください。
+
+## IME カーソルトラッキング
+
+macOS では、ハードウェアカーソルを隠す AI Agent TUI によって、ネイティブ入力メソッドの変換候補ウィンドウがフォーカス中のペインを追跡できなくなることがあります。これらのペインでカーソルアンカーを表示するには、次のように設定します:
+
+```toml
+[experimental]
+reveal_hidden_cursor_for_cjk_ime = true
+cjk_ime_agents = ["claude", "pi", "codex"]
+```
+
+`cjk_ime_agents` で対象を限定すると、関係のないアプリケーションに余分なハードウェアカーソルが表示されるのを避けられます。使用できる Agent 名とカーソル形状については、[設定リファレンス](/docs/config-reference/)でこれらのキーを検索してください。
+
+## プレフィックス入力ソースの切り替え
+
+macOS と Windows では、プレフィックスコマンドとプレフィックスから起動したモードがアクティブな間、Herdr が ASCII 対応の入力ソースへ一時的に切り替えるようにできます:
+
+```toml
+[experimental]
+switch_ascii_input_source_in_prefix = true
+```
+
+macOS ではその時点の ASCII 対応キーボードレイアウトへ切り替えます。Windows では IME を英語（ASCII）入力へ切り替えます。ターミナル入力に戻るかテキストフィールドに入ると、Herdr は以前の入力ソースを復元します。この設定は他のプラットフォームには影響しません。
+
+:::caution[Windows では韓国語 IME のみ対応]
+Windows でのサポートは現時点で韓国語 IME に限定されています。それ以外の言語の IME を使用している場合、この設定は入力ソースを変更しません。
+:::
+
+## 環境変数
+
+| 変数 | 目的 |
+| --- | --- |
+| `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
+```
+
+ログは自動的にローテーションされます。問題を報告するときは、現在のログとローテーションされた関連ファイルを含めてください。
@@ -0,0 +1,128 @@
+---
+title: マシンへの接続
+description: Local と保存済み SSH マシンを 1 つの Herdr ウィンドウで操作し、エージェントをまとめて確認できます。各接続は独立して再接続します。
+---
+
+ローカルの作業とリモートのエージェントを、1 つの Herdr ウィンドウにまとめられます。SSH マシンを一度保存すれば、別のクライアントを開かずに、そのワークスペースと Local を切り替えられます。エージェント一覧には接続中のマシンが含まれ、作業場所や回答待ちのエージェントを確認できます。
+
+各マシンは独自の Herdr サーバー、セッション、プロセスを保持します。1 台への接続が切れても、ほかの接続は切れません。
+
+Herdr は、帯域が限られた接続で画面更新の通信量を減らすため、SSH 圧縮を要求します。互換性のある古い Herdr サーバーでも動作し、キー入力などの入力の届け方は変わりません。Herdr の `-C` オプションは SSH 設定の `Compression no` を上書きします。SSH が外部の ControlMaster を通じて既存接続を再利用する場合、その接続では元の圧縮設定が維持されます。
+
+### SSH 認証の復旧
+
+Linux と macOS で `remote.manage_ssh_config=true` の場合、マシン追加、サイドバー、API 操作は承認済み OpenSSH 接続を共有します。`herdr machine status [<label-or-id>] [--json]` は認証を求めず、現在の接続状態を確認します。**reachable** はリモート Herdr が利用可能という意味で、各 TUI の接続状態ではありません。ターミナルで `herdr machine reconnect <label-or-id>` を実行すると、SSH 認証後に保存済みマシンを検証します。インストールや更新は行いません。開いているクライアントは 30 秒以内に再試行し、再起動は不要です。**`! auth`**、**`! error`**、失敗後の再接続ステータスをクリックすると、最新のエラーと CLI コマンドが通知に表示されます。認証ポップアップは開きません。マシン行の展開・折りたたみは変更されません。
+
+共有接続の `ControlPersist 600` はアイドル状態の 10 分を表すもので、MFA の有効期間ではありません。通信中の接続は維持されますが、企業ポリシー、SSH サーバー、ネットワークによってはそれより早く終了します。ローカル Windows の復旧はまだ対応していません。管理対象外の SSH 接続の認証は利用者の責任です。共有 ControlPath を使わずに `ssh` を実行するだけでは、Herdr の承認にはなりません。ホスト鍵の検証は緩和されず、未知または変更されたホスト鍵は引き続き **Attention** です。
+
+## 接続前の確認
+
+リモートマシンへの通常の SSH アクセスが必要です。最初に確認してください:
+
+```bash
+ssh workbox
+```
+
+`workbox` は SSH config のホスト名です。`ssh://you@server:2222` のような接続先も使えます。
+
+複数マシンへの接続は Linux、macOS、Windows のクライアントに対応し、x86_64 または aarch64 の Linux と macOS サーバー、および x86_64 の Windows サーバーに接続できます。対話型セットアップでは確認後に完全なリモートパッケージをインストールまたは更新できます。バックグラウンド再接続ではインストール済みのパッケージだけを探します。SSH 設定、認証、カスタムバイナリについては [SSH 越しのリモートアタッチ](/ja/docs/persistence-remote/)を参照してください。
+
+## マシンを追加する
+
+インストールや置き換えの前に確認できるよう、対話型ターミナルで実行します:
+
+```bash
+herdr machine add workbox
+```
+
+対話型ターミナルでは、Herdr は実行中のセッションを検出します。1 つだけならそれを選択し、複数ある場合は Up/Down と Enter で選べます。Esc または Ctrl+C でキャンセルします。問い合わせに成功しても実行中のセッションがなければ、セットアップは `default` を使います。Herdr がインストールされていない場合は、`default` 用にインストールするか確認します。インストール済みバイナリがセッションを報告できない場合はエラーを表示します。セッションを明示的に選ぶには `--remote-session <name>` を指定してください。
+
+デフォルトセッションはサイドバーに `workbox` と表示されます。これは `user@` プレフィックスを除いた SSH ホストです。別の名前にするには `--label "Build machine"` を追加します。1 つのプロファイルは 1 つのリモートセッションを対象とし、そのホストの全セッションをまとめるものではありません。非対話型コマンドでは、`--remote-session` がない限り `default` を使います。
+
+検出を省略して特定のセッションを使うには、`--remote-session` を追加します:
+
+```bash
+herdr machine add workbox --remote-session agents
+```
+
+`--label` がない場合、このマシンは `workbox/agents` と表示されます。デフォルト名がすでに使われている場合、`machine add` は `--label` の指定を求めます。
+
+Windows サーバーでは、SSH ユーザーが所有する Herdr プロセスで使われている実行ファイルも確認します。再利用前に機能を検証するため、SSH の `PATH` が古いインストールを指していても、互換性のある実行中ビルドを利用できます。
+
+Herdr はインストール済みバイナリと実行中サーバーをそれぞれ確認し、対象のバックグラウンドサーバーを起動してからプロファイルを保存します。互換性があればクライアントとサーバーのバージョンは一致しなくても構いません。未インストールや非互換の場合は、承認付きのセットアップを行います。実行中サーバーの置き換えが必要なら、サーバーとペインのプロセスを停止する前に確認し、その後に互換サーバーを起動します。デフォルトの回答は No です。インストールと置き換えの両方が必要な場合は、1 回の確認で承認します。`machine add` は実験的なライブハンドオフを使いません。セットアップをキャンセルした場合や失敗した場合、プロファイルは保存されません。
+
+`herdr` で UI を開きます。ローカルクライアントがすでに開いていれば、追加や有効化したマシンは通常 1 秒以内に表示され、選択を変えずにバックグラウンドで接続します。マシン切り替え中の変更は、切り替えの完了後に反映します。セットアップ終了後もリモートサーバーは動き続けます。
+
+## マシンを切り替える
+
+サイドバーでマシンまたはそのワークスペースを選びます。選択中のマシンだけがペイン入力とターミナルサイズを受け取り、表示するターミナル内容とグラフィックスを送信します。ほかの接続済みマシンは、ペイン画面を送らずにワークスペース情報、エージェント状態、通知を更新し続けます。
+
+各マシンの横の矢印をクリックすると、現在のワークスペースを切り替えずに一覧を折りたためます。再接続中のマシンでも操作できます。
+
+キーボードでは `prefix+w` を押し、ワークスペース移動キー（デフォルトは Up/Down）で接続済みマシンのワークスペースをサイドバー順に選びます。Enter で移動を確定し、Esc またはプレフィックスキーで切り替えずにキャンセルします。縮小・展開サイドバーとも、折りたたまれたマシン内の選択行を表示します。デスクトップでは両端で折り返し、モバイルの切り替え画面では先頭と末尾で止まります。切断中のマシンは飛ばします。
+
+別マシンのワークスペースをハイライトしたら、他のキー操作の前に Enter で切り替えてください。現在のマシンでペイン、タブ、ワークスペース、カスタムコマンドの操作が誤って実行されるのを防ぎます。クリックすると、デスクトップでのリモート移動のプレビューはキャンセルされます。展開サイドバーはマシンごとの worktree グループの折りたたみ状態を反映します。
+
+起動時は SSH 接続を待たずに Local を開きます。Local を選ぶと、リモートの応答を待たずに未完了の切り替えをキャンセルします。Local 自体が再接続中なら、準備ができた時点で選択を再開します。Local の新しい画面とターミナル設定が届くと入力できます。応答しないマシンがほかのマシンの入力を妨げることはありません。同じサーバーに接続した複数のクライアントは、それぞれ別のタブを表示できます。同じタブを表示した場合のサイズについては[クライアントとサーバー](/ja/docs/concepts/)を参照してください。
+
+接続が切れると、最後のワークスペースとエージェント状態を暗く表示します。これはキャッシュであり、現在の状態ではありません。新しい接続と対応する画面が届くまで、そのペインへの入力や移動は無効です。再接続しても、使用中のマシンから選択を奪いません。
+
+## 名前の変更、無効化、削除
+
+ラベルやホスト名から推測せず、一覧からプロファイル ID を取得します:
+
+```bash
+herdr machine list
+herdr machine rename <profile-id> --label "New name"
+herdr machine disable <profile-id>
+herdr machine enable <profile-id>
+herdr machine remove <profile-id>
+```
+
+スクリプトでは `machine list` に `--json` を追加できます。
+
+名前の変更は表示ラベルだけを更新し、再接続しません。無効化はプロファイルを残し、削除はプロファイルを忘れます。どちらもクライアントからそのマシンだけを切断し、到達不能なホストでも操作できます。リモートセッションとエージェントは動き続けます。
+
+表示中のマシンを削除または無効化すると Local に戻ります。Local が利用できない場合は、別のリモートを選ばず、その状態を表示して再接続します。有効な保存済みマシンがあれば、Local が失敗または再起動してもクライアントを使い続けられます。
+
+## 接続の問題
+
+- **Reconnecting:** ネットワーク中断、スリープ、SSH 障害の後は自動で再試行します。失敗が続くと待機間隔は最大 2 分まで延び、短時間だけ接続に成功してもリセットされません。1 分間安定して接続できると、次の中断では再び短い間隔で再試行します。SSH 接続はアプリケーションの通信を監視し、通信がない間はヘルスチェックを行うため、切れた接続が Online のままになりません。Local はリモート用のプローブではなく、ネイティブ接続の終了や失敗を検知します。
+- **Attention:** 認証、ホスト鍵の承認、互換サーバーの準備などが必要です。ほかのマシンは利用できます。**`! auth`** は認証失敗、**`! error`** は別の問題を示します。バッジをクリックするとエラーと CLI コマンドを表示します。折りたたみ時はどちらも `!` です。
+- **保存済みマシンのファイルエラー:** カタログを読み取れない、または内容が不正な場合、現在の接続は変更しません。通知を表示して自動で読み取りを再試行します。
+
+両端のインストールがブリッジのアイドル終了に対応している場合、Linux と macOS への保存済みマシン接続は、どちらの方向にも通信がない状態が 1 分続くとリモートブリッジを終了します。スリープ時間も含み、復帰時に期限を確認します。正常なアイドル接続ではヘルスチェックを交換するため、継続的な出力を見るためにキーを入力する必要はありません。ブリッジ終了後もリモートサーバー、セッション、ペインのプロセスは動き続けます。古いインストールとは、この追加機能なしで接続できます。
+
+バックグラウンド接続がプロンプトに回答したり、サーバーのインストール、更新、再起動、ハンドオフを行ったりすることはありません。認証以外の Attention の場合は、Herdr が表示する単独接続用のコマンドを対話型ターミナルで実行してください。例:
+
+```bash
+herdr --remote workbox
+```
+
+プロファイルの接続先を使います。名前付きセッションを選んだ場合だけ `--session <name>` も指定します。セットアップ後、開いているクライアントは自動的に再試行します。`machine reconnect` は Herdr をインストール・更新しません。バージョンが違うという理由だけで実行中サーバーを止めないでください。
+
+認証に失敗したら、まず通常の SSH を確認します。パスフレーズ付きの鍵は、非対話型のバックグラウンド接続を始める前に `ssh-add` で読み込んでください。
+
+リモートペイン内で Git 認証や SSH 署名を使うには、信頼できるホストについて SSH 設定で `ForwardAgent yes` を有効にしてください。Herdr が転送を有効にすることはありません。セッションがエージェント付きで起動した場合、更新済みの Linux と macOS サーバーはペインに安定したエージェントアドレスを与えるため、`--remote` または保存済みマシンが再接続した後も、既存ペインと新規ペインの両方で転送されたエージェントを利用できます。動作中の継承エージェントや先行接続は、後から接続したクライアントや一時的なセットアップ確認より優先されます。それが消えた場合は、別の稼働中アタッチがエージェントを提供できます。
+
+これにはローカルクライアントだけでなく、更新済みのリモートサーバーが必要です。エージェントなしで開始したローカルセッションでは `SSH_AUTH_SOCK` を変更しません。サーバー更新前、またはセッションに初めてエージェントが提供される前に作成されたペインは元の環境を維持するため、安定したアドレスを継承するには一度作り直す必要があります。互換性のある古いサーバーやエージェント転送なしの接続も、通常どおりアタッチできます。
+
+## 設定と自動化
+
+UI はデフォルトでクライアントのローカルテーマ、サイドバー設定、キーバインドを使います。選択中サーバーが公開するカスタムコマンドとプラグインは、そのサーバーで実行します。Herdr はローカルのプラグイン、設定、実行ファイル、シークレットを SSH ホストにコピーしません。リモートにコマンドがなければエラーを表示します。クライアント設定を編集したら UI の `reload config` を使います。[設定](/ja/docs/configuration/)を参照してください。
+
+複数のマシンがある場合、デフォルトの Agent 行に `machine` トークンを表示します。既存のカスタム行は維持されるため、ラベルが必要なら `machine` を追加してください。[サイドバーの行レイアウト](/ja/docs/configuration/)ではマシンラベルの条件付き色も設定できます。
+
+ワークスペース、タブ、ペインの ID とエージェント名はサーバーごとに独立しています。2 台に同じ `w1:p1` や `reviewer` が存在する場合があります。UI でマシンを選んでも、既存ペイン内の CLI は継承したセッションとソケットを使い続けます。リモート自動化では `herdr --machine <label-or-id> agent list` で ID を取得し、操作時にも同じプレフィックスを指定します。CLI は保存済みプロファイルの SSH 接続先とセッションを直接使うため、TUI を開く必要はありません。`--machine` を省略した場合の動作は変わりません。対応コマンド、更新要件、パスの扱いは [CLI リファレンス](/ja/docs/cli-reference/#保存済み-ssh-マシン) を参照してください。
+
+## 更新と保存データ
+
+保存するのは、不透明な ID、ラベル、SSH 接続先、明示的なリモートセッション名、有効状態だけです。パスワード、秘密鍵、エージェントのチケット、SSH 制御ソケットはカタログに保存しません。認証は OpenSSH が扱います。
+
+Herdr は、`--machine` コマンドを繰り返し実行するときに検出を省略できるよう、各マシンのリモート OS と解決済み実行ファイルパスを別途記憶します。既存のプロファイルでは、初回使用時に不足情報を学習します。このキャッシュは任意です。キャッシュファイルがない、不正、または書き込み不能でもコマンドの動作は妨げられません。コマンドは引き続き実行中サーバーの互換性を確認します。キャッシュした実行ファイルがない、または API 転送に対応しなくなった場合、最初の読み取り専用確認中に再検出します。リモートの状態をすでに変更した可能性があるコマンドを自動的に再実行することはありません。
+
+クライアントとサーバーは同一バージョンを要求せず、互換性を合意します。保存済みマシンへの接続には、サーバーの `surface_interest` と `health_check` 能力も必要です。未対応の古いサーバーは、単独接続できても明示的に更新するまで Attention になります。そのほかの未対応メソッドは、該当する操作だけを無効にします。
+
+互換クライアントを更新しても、リモートサーバーを置き換えたりエージェントを停止したりしません。新しいサーバー機能が必要なら、そのサーバーを明示的に更新します。通常の置き換えでは、サーバーとペインのプロセスを停止する前に確認します。
+
+ライブハンドオフは実験的なオプトイン機能です。単独接続のセットアップで対応サーバーを置き換える場合、`herdr --remote` に `--handoff` を明示的に追加できます。通常の接続や認証の修復には不要です。[更新](/ja/docs/install/)と[セッション状態と復元](/ja/docs/session-state/)で、それぞれの操作が何を維持するか確認してください。
@@ -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
+```
+
+リモートサーバーがペインを動かし、ターミナル内容とセッション状態を 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` を使います。単独のリモートセッションをローカル UI で操作し、ローカルクリップボードの画像も貼り付けたい場合は `herdr --remote <host>` を使います。Local と複数の SSH マシンを 1 つのウィンドウで使うには、`herdr machine add <host> --label <label>` で接続先を保存します。[マシンへの接続](/ja/docs/connecting-machines/)を参照してください。
+
+リモートブートストラップの詳細、名前付きリモートセッション、カスタムバイナリ、ダイレクトターミナルアタッチについては[永続化とリモートアクセス](/ja/docs/persistence-remote/)を参照してください。
@@ -0,0 +1,82 @@
+---
+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="マシンへの接続">
+    Local と保存済み SSH マシンを 1 つのウィンドウにまとめ、エージェントを一覧できます。接続はそれぞれ独立して再接続します。
+
+    [マシンを接続する →](/ja/docs/connecting-machines/)
+  </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>
@@ -0,0 +1,158 @@
+---
+title: Herdr のインストール
+description: Linux、macOS、Windows での Herdr のインストール、アップデート、動作確認。
+---
+
+Herdr は Linux、macOS、Windows 向けに安定版チャンネルのバイナリを提供しています。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"
+```
+
+エンドポイントセキュリティによってこのファイルレス PowerShell コマンドがブロックされる場合は、コマンドプロンプトを開いて次を実行します：
+
+```cmd
+curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del install.cmd
+```
+
+インストーラーはプラットフォームに合ったリリースバイナリをダウンロードして PATH 上に配置します。新しい直接インストールは安定版アップデートチャンネルを使います。既存の Windows プレビューインストールは、`herdr channel set stable` で切り替えるまでプレビューに残ります。Windows では PATH が有効なバージョン付きリリースディレクトリを指し、インストーラーは互換性のため `current` と安定した `bin` エイリアスも更新します。そのため、アップデート時に実行中の `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:herdrdev/herdr` も使えます。
+
+## Nix でインストール
+
+すでに Nix を使っている場合、Herdr はソースからビルドする flake を提供しています:
+
+```bash
+nix run github:herdrdev/herdr/v0.x.y
+nix build github:herdrdev/herdr/v0.x.y
+nix profile install github:herdrdev/herdr/v0.x.y
+```
+
+`v0.x.y` は最新のリリースタグに置き換えてください。タグを省略すると `master` を追跡できますが、通常のインストールにはリリースタグを推奨します。
+
+flake は開発用シェルも公開しています:
+
+```bash
+nix develop github:herdrdev/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/herdrdev/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` |
+| Windows x86_64 | `herdr-windows-x86_64.zip` |
+
+Linux または macOS では、実行可能にして PATH 上のどこかに移動します。
+
+```bash
+chmod +x herdr-linux-x86_64
+mv herdr-linux-x86_64 ~/.local/bin/herdr
+```
+
+### Windows アーカイブ
+
+安定版リリースとプレビュープレリリースの両方に `herdr-windows-x86_64.zip` が含まれます。アーカイブには `herdr.exe` とアプリローカルの ConPTY ランタイムが含まれます。展開したディレクトリをまとめて保持し、`herdr.exe` だけをコピーしないでください。
+
+## 動作確認
+
+Herdr を起動します:
+
+```bash
+herdr
+```
+
+シェルが `herdr` を見つけられない場合は、ターミナルを再起動するか、インストール先ディレクトリが PATH に含まれているか確認してください。
+
+## アップデート
+
+Herdr は新しいリリースをチェックし、アプリ内で通知します。手動でアップデートすることもできます:
+
+```bash
+herdr update
+```
+
+`herdr update` は Herdr 自身のインストーラーで管理されているインストール向けです。Homebrew、mise、Nix のインストールは、それぞれのパッケージマネージャーでアップデートしてください。
+
+Linux、macOS、Windows の直接インストールは、デフォルトで安定版アップデートチャンネルを使います。`master` からのプレビュービルドにオプトインするには、チャンネルを設定します:
+
+```bash
+herdr channel set preview
+```
+
+直接インストールを安定版に戻すのも同じ方法です:
+
+```bash
+herdr channel set stable
+```
+
+直接インストールの場合、チャンネルの変更はそのチャンネルをチェックして最新バイナリをインストールします。そのアップデートが失敗した場合は、`herdr update` を実行して設定済みチャンネルから再試行してください。
+
+プレビュービルドは、現在の開発ブランチから定期的に公開される GitHub プレリリースです。次の安定版リリースより前に修正が欲しいときに便利ですが、リグレッションの可能性があります。Homebrew、mise、Nix のインストールはプレビューチャンネルを使いません。
+
+Windows の通常利用には安定版を推奨します。プレビューでは修正をより早く受け取れますが、リグレッションの可能性があるため、そのトレードオフを望む場合に限りオプトインしてください。既存の Windows プレビューインストールは、明示的に切り替えるまでプレビューに残ります。古いプレビュービルドで `herdr channel set stable` が拒否される場合は、プレビューのまま一度 `herdr update` を実行してから、チャンネル切り替えを再試行してください。
+
+デフォルトでは、`herdr update` は新しいバイナリをインストールし、エンドポイント世代 1 のサーバーとペインプロセスを動かしたままにします。再度 Herdr を起動すると、更新済みクライアントで再接続します。クライアントだけの変更はすぐに使えます。新しいサーバー側アクションは、そのサーバーを更新して再起動するまで利用できず、クライアントは切断せずに通知を表示します。エンドポイント世代 1 より前のサーバーだけは、更新時に最後の 1 回の停止が必要です。
+
+完了時に `herdr update` は、古いバージョンのまま動いているサーバーとそれを再起動するコマンド、そして独自の Herdr を動かしている保存済み SSH マシンを一覧表示します。各マシンでも `herdr update` を実行して更新してください。
+
+対応する実行中セッションで実験的なライブサーバーハンドオフにオプトインするには:
+
+```bash
+herdr update --handoff
+```
+
+両方のサーバーがエージェント状態の転送に対応している場合、ライブハンドオフはフックが報告したエージェント状態を次の報告が届くまで維持します。古いサーバーからハンドオフすると、実行中のエージェントが一時的に idle と表示される場合があります。
+
+ライブハンドオフは Homebrew、mise、Nix のパッケージマネージャー経由のアップデートには適用されません。それらのインストールではパッケージマネージャーで更新し、再度 Herdr を実行して更新済みクライアントで再接続します。互換性のある古いサーバーは動き続けます。新しいリリースのサーバー側変更が必要になったときだけ、`herdr server stop` または `herdr session stop <name>` で後から再起動してください。
+
+## 動作要件
+
+安定版チャンネルのバイナリは Linux、macOS、Windows x86_64 で利用できます。サポートされるワークフローと既知の制限は [Windows サポート](/ja/docs/windows-beta/)を参照してください。Windows ARM64 では x86_64 ビルドが Windows のエミュレーション上で動作します。
@@ -0,0 +1,374 @@
+---
+title: インテグレーション
+description: Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、Qoder CLI、Qwen Code、Letta Code、Cursor Agent CLI、MastraCode、Antigravity CLI、Grok CLI 向けの Herdr インテグレーションをインストールします。
+---
+
+Herdr は対応するエージェントを自動的に検出します。エージェントのインテグレーションをインストールすると、サーバーの再起動後に Herdr が同じセッションを resume できます。一部のインテグレーションはエージェントの状態も直接報告します。Herdr が対応するエージェントと、自ら Herdr に対応するエージェントについては[エージェント](/ja/docs/agents/)を参照してください。
+
+エージェントネイティブのセッション復元、直接のライフサイクル報告、またはその両方が欲しいときにインテグレーションを使ってください。状態権威モデルの全体像は[エージェント](/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 mastracode
+herdr integration install qodercli
+herdr integration install qwen
+herdr integration install letta
+herdr integration install cursor
+herdr integration install antigravity-cli
+herdr integration install grok
+```
+
+## インテグレーションをアンインストールする
+
+```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 mastracode
+herdr integration uninstall qodercli
+herdr integration uninstall qwen
+herdr integration uninstall letta
+herdr integration uninstall cursor
+herdr integration uninstall antigravity-cli
+herdr integration uninstall grok
+```
+
+Herdr は Linux/macOS の統合設定と全プラットフォームの新規ファイルをアトミックに保存し、Windows の既存ファイルは権限を維持するため、バックアップ後に同じファイルを更新します。Windows でバックアップが通知された場合は、再試行前にエージェントを終了して設定を確認し、未完了の `.herdr-backup.pending` は復旧元に使わず設定が正しいことを確認してから削除するか、必要なら完成済みの `.herdr-backup` の内容を既存ファイルに書き戻し（ファイルがない場合は先に意図した権限を設定）、設定が正しいことを確認してからバックアップを削除してください。
+
+## Herdr がインテグレーションをどう使うか
+
+どのインテグレーションも、エージェントが今どのセッションにいるかを Herdr に伝えるので、サーバーの再起動後に Herdr がそのセッションを resume できます。`[session] resume_agents_on_restore = false` で無効にできます。
+
+Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、MastraCode のインテグレーションは、エージェントの状態も報告します。報告している間、Herdr は画面を読む代わりにその報告を使います。Codex は `--no-daemon` で起動した場合にターン状態を報告し、表示中のブロッカーは引き続き画面検出で扱います。その他のインテグレーションでは、状態は画面検出に任せます。
+
+エージェントネイティブのセッション復元には最新の 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`、Qwen Code は `1`、Letta Code は `1`、Cursor Agent CLI は `1`、Grok CLI は `2`、OpenCode は `5`、Kilo Code CLI は `1`、Hermes Agent は `5`、MastraCode は `1`、Antigravity CLI は `1` です。インストール済みバージョンは `herdr integration status` で確認してください。
+
+## 独自エージェントを統合する
+
+コーディングエージェントを開発している場合は、Herdr にネイティブサポートを追加せずに、自分のコードからエージェントの状態と resume コマンドを Herdr に報告できます。[エージェントに Herdr 対応を追加する](/ja/docs/add-herdr-support/)を参照してください。
+
+## 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` に書き込みます。Pi の agent ディレクトリが存在する場合、Herdr は 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` に書き込みます。OMP の agent ディレクトリが存在する場合、Herdr は 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 のスクリーンマニフェスト検出から得られます。
+
+Claude 統合 v10 は、文書化された `SessionStart` の source 値 `startup`、`resume`、`clear`、`compact`、`fork` のみに一致します。これにより、ほかの Claude 互換フックを無効にせずに、Grok の `new` と `load` イベントがインポートされた Herdr の Claude フックを起動するのを防ぎます。アップグレード後に Claude 統合を再インストールして、従来のワイルドカードマッチャーを移行してください。Claude に新しい source 値が追加された場合は、統合の更新が必要です。
+
+Herdr はデフォルトで `~/.claude` を使い、`CLAUDE_CONFIG_DIR` が設定されていればそちらを使います。Claude の設定ディレクトリはあらかじめ存在している必要があります。インストールは `hooks/herdr-agent-state.sh` を書き込み、`settings.json` に Herdr のフックエントリを追加します。アンインストールは一致するフックエントリを削除し、フックスクリプトを削除します。
+
+## Codex
+
+Codex フックをインストールします:
+
+```bash
+herdr integration install codex
+```
+
+Codex を `--no-daemon` で起動すると、フックがローカルソケット API を通じてセッション識別とターンの開始・終了を報告します。表示中のブロッカーやフックが使えない場合は、引き続き画面検出が補います。共有 Codex デーモンは別のペインへフックを送ることがあるため、確実な報告には `--no-daemon` を使ってください。デーモンの自動起動を無効にするだけでは、既存のデーモンは停止しません。
+
+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 検出から得られます。
+
+`XDG_CONFIG_HOME` が設定されていれば、Herdr は `$XDG_CONFIG_HOME/devin` を使います。それ以外では、Linux と macOS では `~/.config/devin`、Windows では `%APPDATA%\devin` を使います。Devin の設定ディレクトリはあらかじめ存在している必要があります。インストールは Unix では `herdr-agent-state.sh`、Windows では `herdr-agent-state.ps1` を書き込み、`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
+```
+
+この連携は OpenCode V1 `1.18.29` 以降と OpenCode V2（beta `19242` で検証済み）に対応します。OpenCode の設定ディレクトリはあらかじめ存在している必要があります。Herdr はサーバー側のエントリポイントを `~/.config/opencode/plugins/herdr-agent-state.js` に、共通 TUI プラグインを同じ設定ディレクトリの `herdr-tui-session.js` に、V2 TUI エントリポイントを `herdr-opencode/tui.js` にインストールします。
+
+インストール時、V1 TUI プラグインを `tui.jsonc` に、V2 TUI プラグインを `cli.json` に登録し、他の設定やプラグインは保持します。`tui.json` に既存の V1 登録がある場合もインストール済みとみなし、`tui.jsonc` を作成せずに再利用します。アンインストールでは、両方の TUI 設定ファイルから Herdr の登録を削除し、ファイルと他の設定は保持します。OpenCode に移行すべき V1 TUI 設定（`tui.json` または `kv.json`）が残っている場合、Herdr は初回起動時の移行を妨げないよう登録を見送ります。その場合は一度 `opencode2` を起動してから連携を再インストールしてください。それ以外の場合は Herdr が `cli.json` を作成してプラグインを登録します。インストール後は OpenCode TUI を再起動してください。アンインストールは管理対象のプラグインファイルと設定項目を削除します。
+
+V2 のライフサイクル報告はペイン内の TUI で実行され、複数のペインが同じ OpenCode サーバーを共有する場合も、選択されたルートセッションにイベントを対応付けます。完了時または中断時に working 状態を解除し、未処理の権限要求やフォーム、実行失敗は blocked 状態を維持します。V2 Mini とヘッドレスクライアントは TUI プラグインを実行しないため、このライフサイクル報告は利用できません。
+
+V1 TUI はペインで選択したセッションとその子孫を追跡します。いずれかが実行中・再試行中なら working、権限要求や質問が未処理なら blocked を維持します。接続時に既存の状態を読み込み、キャンセル済みツールの要求が再接続後に blocked を復活させることはありません。サブエージェントの閲覧では元のセッション群を維持し、子セッションへ直接接続した場合は兄弟ではなくその子孫だけを追跡します。
+
+ローカル V1 の `opencode run` と `opencode --mini` は従来のサーバーフックを維持します。この変更は Mini やヘッドレスクライアントにペイン固有のライフサイクル報告を追加するものではありません。連携の更新後は TUI と共有 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/` に書き込み、その `config.yaml` で `herdr-agent-state` を有効にします。`HERMES_HOME` のデフォルトは Unix では `~/.hermes`、Windows では `%LOCALAPPDATA%\hermes` です。Hermes の設定ディレクトリはあらかじめ存在している必要があります。プラグインを読み込ませるため、インストール後に Hermes を再起動してください。アンインストールはプラグインディレクトリを削除し、`plugins.enabled` から `herdr-agent-state` を削除します。
+
+このプラグインは、Hermes が Herdr のペイン内で動いている間、resume 可能なセッション id を報告します。Herdr は `working`、`idle`、`blocked` にスクリーンマニフェスト検出を使い、報告されたセッション 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 します。
+
+フックがインストールされていないときは、スクリーンマニフェスト検出が引き続き利用できます。
+
+## Qwen Code
+
+Qwen Code フックをインストールします:
+
+```bash
+herdr integration install qwen
+```
+
+`SessionStart` フックはネイティブ復元用のセッション識別だけを報告します。ライフサイクル状態は引き続き Herdr のスクリーンマニフェスト検出が決定します。
+
+Herdr はデフォルトで `~/.qwen` を使い、`QWEN_HOME` が設定されていればそちらを使います。Qwen の設定ディレクトリはあらかじめ存在している必要があります。インストールは `hooks/herdr-agent-session.sh`（Windows では `hooks/herdr-agent-session.ps1`）を書き込み、`settings.json` に Herdr エントリを追加します。アンインストールは一致するエントリと管理対象スクリプトだけを削除します。
+
+Herdr は保存された Qwen Code セッションを `qwen --resume <id>` で resume します。
+
+## Letta Code
+
+Letta Code インテグレーションのインストールは実験的な CLI 専用機能です。Settings のインテグレーション一覧や JSON インテグレーション API には含まれません。`herdr integration status` では `letta (experimental)` と表示されます。エージェント検出と `herdr agent start --kind letta` は、このインストール方法の制限とは別にサポートされています。
+
+Letta Code フックをインストールします:
+
+```bash
+herdr integration install letta
+```
+
+静かな `SessionStart` フックは、ネイティブ復元用の会話 ID を報告します。Letta Code の状態は引き続き Herdr のスクリーンマニフェスト検出から得られます。
+
+Herdr は `~/.letta` を使います。設定ディレクトリはあらかじめ存在している必要があります。インストールは `hooks/herdr-agent-session.sh`（Windows では `hooks/herdr-agent-session.ps1`）を書き込み、`settings.json` に Herdr エントリを追加します。アンインストールは一致するエントリと管理対象スクリプトだけを削除します。
+
+Herdr は名前付き会話を `letta --conversation <id>` で resume します。デフォルト会話は `default:<agent-id>` として記録し、`letta --conversation default --agent <agent-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`（Windows では `herdr-agent-state.ps1`）を書き込み、`hooks.json` に Herdr の `sessionStart` エントリを追加します。アンインストールは一致するフックエントリを削除し、フックスクリプトを削除します。
+
+Cursor がセッション開始イベントを発行した後、Herdr は報告されたセッション id を使って `cursor-agent --resume <id>` でペインを resume できます。Herdr がペインを復元するとき、`cursor-agent` コマンドが `PATH` にある必要があります。Herdr は汎用の `agent` コマンドを起動しません。
+
+## MastraCode
+
+MastraCode フックをインストールします:
+
+```bash
+herdr integration install mastracode
+```
+
+このフックは、MastraCode のライフサイクル状態とスレッド識別を Herdr に報告し、権威ある `idle`、`working`、`blocked` 状態とネイティブ復元を提供します。MastraCode にはスクリーンマニフェストのフォールバックはありません。MastraCode が Herdr ペイン内で動いている間、状態はフックから得られます。
+
+Herdr は `~/.mastracode` を使います。インストールは `hooks/herdr-agent-state.sh`（Windows では `hooks/herdr-agent-state.ps1`）を書き込み、`hooks.json` に Herdr のコマンドエントリを追加します。ディレクトリがなければ作成します。アンインストールは一致するフックエントリを削除し、フックスクリプトを削除します。
+
+Herdr は保存された MastraCode スレッドを `mastracode --thread <id>` で resume します。
+
+## Antigravity CLI
+
+Antigravity CLI フックをインストールします:
+
+```bash
+herdr integration install antigravity-cli
+```
+
+Herdr はデフォルトで `~/.gemini/config/` を使い、`ANTIGRAVITY_CLI_CONFIG_DIR` が設定されていればそちらを使います。これは Antigravity CLI がグローバルカスタマイズを読み込むディレクトリで、あらかじめ存在している必要があります。インストールは `hooks/herdr-agent-state.sh`（Windows では `herdr-agent-state.ps1`）を書き込み、`hooks.json` に Herdr 所有の `herdr` ブロックを追加します。Antigravity CLI は `hooks.json` をフック名で管理するため、インストールはそのブロックだけを書き換え、ほかの名前付きフックには触れません。アンインストールは `herdr` ブロックとフックスクリプトを削除します。
+
+このインテグレーションはセッション専用です。ペインで実行中の会話を報告しますが、エージェント状態は報告しません。そのため、Herdr は Antigravity CLI の画面表示から `working`、`idle`、`blocked` を引き続き判定します。
+
+フックは `PreInvocation` で実行されるため、最初のプロンプト送信後に Herdr が会話を認識します。それ以降、Herdr サーバーの再起動後に `agy --conversation <id>` でペインを resume できます。
+
+## Grok CLI
+
+Grok CLI フックをインストールします:
+
+```bash
+herdr integration install grok
+```
+
+このフックは、Grok CLI が Herdr のペイン内で動いている間、Grok の `SessionStart` フックを通じてセッション識別を報告します。Grok の状態は Herdr のスクリーンマニフェスト検出から得られます。
+
+Herdr はデフォルトで `~/.grok` を使い、`GROK_HOME` が設定されていればそちらを使います。Grok の設定ディレクトリはあらかじめ存在している必要があります。Grok はそのディレクトリ内のすべての `hooks/*.json` ファイルを統合するため、インストールは Herdr の `SessionStart` エントリだけを含む `hooks/herdr.json` と `hooks/herdr-agent-state.sh`（Windows では `hooks/herdr-agent-state.ps1`）を書き込み、ほかのフックファイルには触れません。アンインストールは Herdr 所有のこの 2 ファイルだけを削除します。
+
+Grok がセッション開始イベントを発行した後、Herdr は報告されたセッション id を使って `grok --resume <id>` でペインを resume できます。
+
+## カスタムステータスラベル
+
+インテグレーションは、ライフサイクル状態を意味的な状態としてのみ報告します。たとえば、ライフサイクル報告に表示フィールドを加えず、エージェントを `working` として報告します。
+
+```bash
+herdr pane report-agent w1:p1 \
+  --source custom:docs \
+  --agent docs-bot \
+  --state working
+```
+
+Herdr 管理のインテグレーションと並走するユーザーフックは、`report-agent` ではなくメタデータを使うべきです。メタデータは、インテグレーションの `idle`、`working`、`blocked` やセッション復元の権威を奪わずに表示を変えます。`--agent` と `--applies-to-source` は表示フィールド (`--title`、`--display-agent`、`--state-label`) だけを保護します。トークンパッチは常に適用され、クリアまたは TTL の更新は報告側が管理します。`--display-agent` は表示名を変更します。
+
+```bash
+herdr pane report-metadata "$HERDR_PANE_ID" \
+  --source user:claude-title \
+  --agent claude \
+  --title "Refactor auth middleware" \
+  --display-agent "Claude: auth" \
+  --token summary="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 内で動いていること、そして該当のフックまたはプラグインが同じユーザーアカウントにインストールされていることを確認してください。
@@ -0,0 +1,140 @@
+---
+title: キーボード
+description: プレフィックスとは何か、最初に覚えるべきバインド、プレフィックスなしで運用する方法。
+---
+
+:::tip[tmux や zellij から乗り換え?]
+このモデルはすでにご存じのはずです。完全なデフォルトキーマップと設定構文は[キーバインドリファレンス](/ja/docs/configuration/#キーバインド)へどうぞ。
+:::
+
+Herdr はマウスネイティブです。キーバインドをひとつも覚えなくても、ペイン、タブ、ワークスペース、エージェントをクリックし、分割境界をドラッグし、右クリックメニューを使えます。キーボード操作は任意のレイヤーであり、必須ではありません。
+
+## プレフィックスとは何か
+
+ターミナルマルチプレクサは、ターミナルとその中で動くプログラムの間に位置します。プログラムはすでにほとんどのキーの組み合わせを使っています: `ctrl+c` は中断、`ctrl+r` は履歴検索、エディタは残りのほぼすべてを占有します。もし Herdr がよく使われるキーを直接奪えば、中のプログラムを壊してしまいます。
+
+プレフィックスはこれを解決します。プレフィックスキー (デフォルト `ctrl+b`) を押すと、次のキー入力はターミナルではなく Herdr に送られます。`prefix+c` は「`ctrl+b` を押して離し、次に `c` を押す」という意味です。何十ものキーを予約する代わりに、ひとつだけ予約します。
+
+いつでも `prefix+?` を押すと、すべての有効なバインドが表示されます。キーバインドヘルプで `/` を押すと、アクションとショートカットを絞り込めます。Backspace でフィルターを編集し、`ctrl+u` でクリアできます。
+
+## まずこの 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/#キーバインド)にあります。
+
+Goto ピッカー (`prefix+g`) は、各エージェントとターミナルをワークスペースごとに一行ずつ表示します。分割タブのペインも隠さず表示されます。行をクリックするか Enter を押すと、そのペインへ直接移動します。`/` で名前、エージェントの種類、タブ、ワークスペース、ブランチ、パスを検索できます。検索入力中でなければ上下矢印キーまたは `j/k` で行を移動します。左右矢印キーは前後のワークスペースの最初のエージェントまたはターミナルへ移動し、端では折り返しません。検索入力中は左右矢印キーでテキストカーソルを動かします。`b/w/i/d` で blocked、working、idle、done のエージェントに絞り込み、`a` ですべてのターミナルに戻します。選択した移動先の場所とパスは一覧の下に表示されます。一覧が収まらない場合は、マウスホイール、スクロールバーのトラックのクリック、つまみのドラッグで、移動先を開かずにスクロールできます。
+
+Esc または Ctrl+[ でワークスペースナビゲーションを終了します。Go To では、Shift が必要な配列でも `/` で検索を開けます。
+
+ペインへの入力はアプリが要求するキーボードモードに従います。通常のシェルには Ctrl+Shift+letter を制御バイトとして送り、表現できない Super、Hyper、Meta の組み合わせは送りません。Kitty キーボード入力を使うアプリには、要求した修飾キーとキーイベントを送ります。report-all モード以外では、修飾付き Enter、Tab、Backspace の解放レポートは送りません。テンキーと修飾キー単独の押下も転送しません。
+
+非ラテン文字の配列では、Ctrl+W など Ctrl 単独の組み合わせに、Kitty 対応ホストが報告する物理的なベースキーを使えます。ラテン文字の配列、Ctrl+Shift、AltGr は配列上の意味を保持します。物理キーを報告しないターミナルでは、同じ配列非依存のショートカットは使えません。
+
+## テキスト欄の編集
+
+Herdr の名前入力、worktree のブランチ名、フィルター、コピーモードの検索欄では、カーソル位置で編集できます。以下は Herdr 自身の入力欄の操作であり、ペイン内のシェルやエージェントの操作は変わりません。
+
+| 操作 | キー |
+| --- | --- |
+| 1 文字移動 | Left / Right、Ctrl+B / Ctrl+F |
+| 先頭 / 末尾へ移動 | Home / End、Ctrl+A / Ctrl+E |
+| 1 単語移動 | Alt+B / Alt+F |
+| 前の文字を削除 | Backspace、Ctrl+H |
+| 次の文字を削除 | Delete、Ctrl+D |
+| 先頭 / 末尾まで切り取り | Ctrl+U / Ctrl+K |
+| 前の単語を切り取り | Ctrl+W、Alt+Backspace、Ctrl+Backspace |
+| 次の単語を切り取り | Alt+D |
+| 最後に切り取ったテキストを挿入 | Ctrl+Y |
+
+入力と貼り付けはカーソル位置に挿入されます。移動と削除は Unicode の書記素境界を尊重し、長い値は横にスクロールします。切り取ったテキストは現在の入力欄だけで保持し、システムのクリップボードは使いません。Alt ショートカットにはターミナルの Alt/Meta 報告が必要です。Enter と Esc は引き続きダイアログの確定とキャンセルに使います。
+
+## コピーモード
+
+`prefix+[` を押すと、フォーカス中のペインでコピーモードに入ります。`h/j/k/l`、tmux 形式の `w/b/e`、`{`/`}` で移動します。`/` または `?` で前方または後方のリテラル検索を開始し、`n` または `N` で同じ方向または逆方向に繰り返します。クエリに大文字が含まれる場合だけ大文字と小文字を区別します。`v` または Space で選択を開始し、`y` または Enter でコピーし、`q` または Esc でコピーせずに抜けます。Esc は終了する前に、アクティブな選択または検索を消します。コピーモードはペインのプロセスを停止しません。最下部では出力を追従し、履歴へ移動するとその位置を保ちます。マウスのドラッグ選択なら、コピーモードに入らずにそのままコピーできます。
+
+マウスのドラッグ選択と、`v`、Space、`V` で開始した選択は、出力や再描画が続いても維持されます。選択範囲の一部が表示領域の外にある場合も同様です。コピーするのは固定されたスナップショットではなく、その範囲に現在あるテキストです。ペインのサイズ変更や通常画面と代替画面の切り替えでは、引き続き選択が解除されます。検索結果とダブルクリックによる単語選択では、内容変更のチェックが維持されます。
+
+## 何でも変更できる
+
+プレフィックス自体を含め、すべてのバインドは設定可能です:
+
+```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 で別のコードを選びます。
@@ -0,0 +1,52 @@
+---
+title: マーケットプレイス
+description: GitHub 上のコミュニティ製 Herdr プラグインを探し、自分のプラグインを掲載する方法。
+---
+
+Herdr プラグインマーケットプレイスは、コミュニティ製プラグインを探せるインデックスです。
+[herdr.dev/plugins](/plugins/) で閲覧できます。これは公開 GitHub リポジトリの
+自動インデックスであり、審査済みカタログではありません。
+
+## プラグインを探す
+
+[マーケットプレイス](/plugins/)には、GitHub トピック `herdr-plugin` が付いており、
+デフォルトブランチに必須メタデータを解析できる `herdr-plugin.toml` が 1 つ以上ある
+公開リポジトリが掲載されます。リポジトリとプラグインのメタデータを検索でき、
+リポジトリカードを人気順、最近の活動順、新着順で並べ替えられます。各カードは
+ソースリポジトリにリンクし、その中で検出されたすべてのプラグインを表示します。
+
+掲載は自動かつ無審査です。掲載されているのはリポジトリが自らトピックを
+付けたからであって、Herdr が検証したからではありません。インストールする前に
+[信頼に関するガイダンス](/ja/docs/plugins/#信頼とセキュリティ)を確認してください。
+
+## プラグインをインストールする
+
+マーケットプレイスはインストールの上に発見の仕組みを足すものであり、
+インストールを置き換えるものではありません。どのプラグインも GitHub から
+直接インストールできます:
+
+```bash
+herdr plugin install owner/repo[/subdir...]
+```
+
+ルートまたはサブディレクトリに `herdr-plugin.toml` マニフェストを置いた
+通常の公開 GitHub リポジトリを公開すれば、このコマンドが機能します。
+マニフェストと作成方法のリファレンスは[プラグイン](/ja/docs/plugins/)を
+参照してください。
+
+## 自分のプラグインを掲載する
+
+公開リポジトリに GitHub トピック `herdr-plugin` を追加し、デフォルトブランチに
+必須メタデータを解析できる `herdr-plugin.toml` を 1 つ以上置いてください。
+マニフェストはルートにもサブディレクトリにも配置できます。マーケットプレイスは
+1 リポジトリにつき 1 枚のカードを使い、有効な各マニフェストを個別にインストール
+できるプラグインとして表示します。インデックスは 30 分ごとに自動更新されます。
+
+## 掲載に表示される内容
+
+各カードには GitHub リポジトリの名前、オーナー、説明、スター数、主要言語、
+最終 push 時刻が表示されます。プラグイン行には各マニフェストの `name` と `version`
+が表示され、正確なソースディレクトリにリンクします。インデックスにはパス、`id`、
+`name`、`version`、`platforms`、`min_herdr_version` と、デフォルトブランチの正確な
+コミットが記録されます。フォーク、アーカイブ済みリポジトリ、有効なプラグイン
+マニフェストがないリポジトリ、不正なメタデータは一覧から除外されます。
@@ -0,0 +1,155 @@
+---
+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/)を参照してください。
+
+Linux と macOS のサーバーは `SIGHUP` を無視するため、起動元シェルの切断ではペインは停止しません。意図的に停止するには `herdr server stop` または `SIGTERM` を使ってください。以前 `SIGHUP` を使っていたスクリプトは変更が必要です。終了ログには停止理由が記録されます。
+
+## 名前付きセッション
+
+独立した Herdr サーバーが欲しいときは名前付きセッションを使います。
+
+```bash
+herdr session list
+herdr session attach work
+herdr session attach side-project
+herdr session stop work
+herdr session delete side-project
+```
+
+名前付きセッションは独自のペイン、タブ、ワークスペース、ソケット、ランタイム状態を持ちます。グローバル設定ファイルは共有されます。
+
+セッションを削除するときは、大文字と小文字も含めて `herdr session list` に表示される名前を正確に指定してください。大文字と小文字を区別しないファイルシステムでは、`herdr session delete foo` は `Foo` という名前のセッションの削除を拒否します。
+
+スクリプトでは `--json` を使ってください:
+
+```bash
+herdr session list --json
+herdr session stop work --json
+herdr session delete side-project --json
+```
+
+## 保存済み SSH マシン
+
+Local と複数の SSH マシンを 1 つのウィンドウで使うには、[マシンへの接続](/ja/docs/connecting-machines/)を参照してください。セットアップ、切り替え、再接続、設定、リモート自動化を説明しています。保存済みマシンを削除してもクライアントが切断されるだけで、リモートセッションは停止しません。
+
+## SSH 越しのリモートアタッチ
+
+[Herdr での作業の進め方](/ja/docs/how-to-work/)でリモート接続の方法を比較しています。サーバーに SSH してそこで `herdr` を実行する tmux スタイルの方法、保存済み SSH マシンで複数の接続先をまとめる方法、ローカルマシンから単独のセッションに接続する方法があります:
+
+```bash
+herdr --remote workbox
+herdr --remote ssh://you@server:2222
+```
+
+サイドバーの幅、セクションの分割位置、折りたたんだグループ、エージェントの並び順は、接続先とセッションごとにローカルへ保存されます。同じ接続先とセッションに再接続すると復元されます。SSH エイリアスやセッションが異なる場合は別の設定になります。
+
+このモードでは、リモートサーバーがペインを動かし、ターミナル内容とセッション状態を SSH 越しに送信します。ローカルの Herdr がサイドバー、メニュー、テーマを含む UI を描画します。クライアントがローカルで動くため、Herdr は画像クリップボードの貼り付けのようなローカルデスクトップ機能をリモートセッションにブリッジできます。画像をリモートの一時ファイルにコピーし、そのパスを貼り付けます。
+
+デフォルトでは、`herdr --remote` はそのアタッチにローカルの Herdr キーバインドを使います。リモートサーバーの設定が異なっていても、ローカルの操作感覚を維持できます。ローカルキーバインドを編集したら、UI の `reload config` でデタッチせずに反映できます。リモートサーバーの設定を使いたい場合は `--remote-keybindings server` を使います。ローカルのカスタムコマンドキーバインドは送信されません。それらのコマンドはリモートホスト上で実行されてしまうからです。
+
+繰り返し接続する相手は SSH config を使ってください:
+
+```text
+Host workbox
+  HostName server.example.com
+  User you
+  Port 2222
+```
+
+その後はこれでアタッチできます:
+
+```bash
+herdr --remote workbox
+```
+
+リモートアタッチと保存済み SSH マシンは、Linux、macOS、Windows のクライアントから、x86_64 または aarch64 の Linux/macOS ホスト、および x86_64 の Windows ホストへの接続に対応します。Windows ARM64 ホストは、Windows の x64 エミュレーションで x64 ビルドを実行するベストエフォート対応です。不具合や問題が発生する可能性があります。ホストが ARM64 を報告した場合、明示的なリモートアタッチと保存済みマシンのセットアップ時にエミュレーションの注意書きを表示します。両端が安定したエンドポイント世代に対応していれば、バージョンは一致しなくても構いません。Linux/macOS ではリモートの `PATH` 上の互換バイナリを優先し、次に一般的な直接インストール、Homebrew、mise、Nix のパスを確認します。Windows では `PATH` と現在有効な管理対象リリースを確認します。互換バイナリがなければ、対話的な実行はインストールや更新の確認を求め、非対話的な実行はホストを変更せず失敗します。Linux/macOS では `~/.local/bin/herdr` に、Windows ではアプリローカル ConPTY ランタイムを含む完全なパッケージをインストールします。リモートの `PATH` に `~/.local/bin` がない場合は警告します。
+
+デフォルトでは、`herdr --remote` はユーザーの SSH config を最初に include し、その後にフォールバックのキープアライブ設定を加えた一時的な SSH config を通してリモートセットアップとブリッジを実行します。既存のユーザーのキープアライブ設定が優先されます。Linux と macOS クライアントは接続再利用用のプライベートなアタッチ単位コントロールソケットも使いますが、Windows OpenSSH では使いません。Herdr が生成する設定やコントロールソケットを使わず通常の `ssh` を使うには `[remote].manage_ssh_config = false` を設定してください。
+
+リモート接続は通常の OpenSSH 認証を使います。非対話型シェル、スクリプト、CI、モバイルターミナルなどで鍵のパスフレーズを入力できない場合は、先に ssh-agent へ鍵を追加してください:
+
+```bash
+ssh-add
+herdr --remote workbox
+```
+
+認証に失敗したら、まず `ssh workbox` で通常の SSH 接続を確認してください。
+
+バージョンが違うだけでは、実行中のリモートサーバーを置き換えたり再起動したりしません。必要な互換性や独立したバックグラウンド起動に未対応のサーバーは、停止前に確認します。保存済みマシンには画面配信とヘルスチェックの能力も必要です。[マシンへの接続](/ja/docs/connecting-machines/)を参照してください。デフォルトの回答は No で、停止するとペインのプロセスも終了します。この一度限りの更新で、対応サーバーのプロセスを実験的なライブハンドオフで維持したい場合は `--handoff` を渡します:
+
+```bash
+herdr --remote workbox --handoff
+```
+
+先にサーバーへ SSH してそこで `herdr` を実行した場合、Herdr は完全にサーバー上で動きます。このモードは便利でシンプルですが、通常のターミナルテキスト貼り付けを超えてローカルデスクトップのクリップボードにはアクセスできません。
+
+Linux/macOS ホストでは、プラットフォームが一致する直接インストールなら現在のローカルバイナリをコピーできます。Homebrew、mise、Nix のインストール、異なるプラットフォーム、または Windows ホストの場合は、`https://herdr.dev/latest.json` から現在のクライアントバージョンに対応するリリースアセットをダウンロードします。
+
+ローカルビルドやカスタムパッケージを使うには、リモートアタッチ前に `HERDR_REMOTE_BINARY` にローカルファイルパスを設定します。Linux/macOS 向けには実行ファイル、Windows 向けには完全な `herdr-windows-x86_64.zip` パッケージを指定してください。
+
+```bash
+HERDR_REMOTE_BINARY=target/release/herdr herdr --remote workbox
+```
+
+## リモートの名前付きセッション
+
+リモートホスト上の名前付きセッションにアタッチするには、`--remote` と一緒に `--session` を使います:
+
+```bash
+herdr --remote workbox --session agents
+```
+
+## ダイレクトターミナルアタッチ
+
+完全な Herdr アタッチはワークスペース UI 全体を開きます。ダイレクトアタッチは、サーバーが所有するターミナルをひとつだけ、現在のターミナルに開きます。
+
+ダイレクトターミナルアタッチは Linux と macOS で利用でき、ネイティブ Windows では利用できません。
+
+エージェントターゲットでアタッチ:
+
+```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
+```
+
+描画済みターミナルデータだけが必要な外部ブリッジには、読み取り専用のオブザーバーを使えます:
+
+```bash
+herdr terminal session observe w1:p1 --cols 120 --rows 40
+```
+
+base64 の ANSI データを含む `terminal.frame` を改行区切り JSON で出力し、サーバーがストリームを閉じると `terminal.closed` を出力します。複数のオブザーバーが同じターミナルを監視でき、入力、リサイズ、スクロール、所有権を取得することはありません。
+
+対話型ブリッジには書き込み可能なコントローラーを使います:
+
+```bash
+herdr terminal session control w1:p1 --takeover --cols 120 --rows 40
+```
+
+同じフレームを出力し、標準入力から改行区切り JSON コマンドを読み取ります。`terminal.input` はテキストまたは base64 データ、`terminal.resize` は表示サイズ、`terminal.scroll` はビューポートのスクロール、`terminal.mouse` はマウス報告を有効にしたアプリへのセル位置のマウスイベント、`terminal.release` はコントローラーの終了を扱います。入力とリサイズを所有できるコントローラーは 1 つだけです。
@@ -0,0 +1,381 @@
+---
+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"]
+
+[[startup]]
+command = ["node", "dist/restore.js"]
+
+[[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 update
+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` を使ってください。更新や再インストール後も、実行中のコマンドとペインは
+元のファイルを使い続け、新しい呼び出しは設定の再読み込みなしで新しい版を使います。
+既存のプロセスは再起動されず、起動フックは通常どおり次のサーバー起動時に実行されます。
+`plugin update` は対象を省略すると GitHub 管理の全プラグインを更新します。
+プラグイン id または GitHub ソースを指定すれば、その対象だけを更新します。
+インストール時の ref を再取得し、コミットが変わっていなければスキップします。
+一括更新ではローカルにリンクされたプラグインを無視します。非対話的な更新には `--yes` を使います。
+インストール済みおよびリンク済みのプラグインと、その有効・無効の状態は現在の
+ユーザー全体で共有され、すべての Herdr セッションから利用できます。Herdr サーバーが
+動作していないときでも `plugin install` と `plugin link` で登録できます。
+Herdr 0.7.3 の名前付きセッションだけにインストールしたプラグインは、再度 install
+または link してください。既存のプラグイン設定と状態はそのまま残ります。
+ローカルにリンクされたプラグインへの上書きインストールは拒否されます。先に
+ローカルプラグインを unlink または uninstall してください。`plugin install` と
+`plugin link` はプラグインの設定・状態ディレクトリを作成し、
+`plugin config-dir <id>` はセットアップドキュメントやシェルスクリプト向けに
+設定ディレクトリを表示します。
+
+`plugin uninstall <id-or-source>` は登録を解除し、プラグイン id または install と同じ
+`owner/repo[/subdir...]` 省略記法を受け付けます。更新、再インストール、アンインストール後も
+実行中のプラグインが完了できるようファイルを保持します。使用中のサーバーが終了した後、
+次に成功したインストール／更新、またはサーバー起動時に、不要な管理インストールを削除します。
+設定の再読み込みでは古いインストールを解放しません。サーバー停止前にプラグインの作業を
+止めてください。サーバー終了後も残るプロセスは削除から保護されません。プラグインは
+親コマンドやペインが終了する前に、切り離したバックグラウンドプロセスを停止する必要があります。
+削除追跡のない旧インストール、設定、状態は保持されます。
+`plugin unlink <id>` は登録解除のみを行いファイルには触れないため、ローカル開発に便利です。
+
+サンプル集のリポジトリは `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 は
+ビルドの失敗を報告しますが、足りないツールチェーンをインストールすることはありません。
+
+## スタートアップフック
+
+`[[startup]]` コマンドは、Herdr がセッションを復元し、API ソケットの準備が整った後に、
+有効なプラグインごとに一度実行されます。ライブハンドオフで新しいサーバーが引き継いだ
+ときにも再実行されますが、クライアントの接続、設定の再読み込み、プラグインの link や
+enable では実行されません。Herdr はこれらを非同期で開始し、完了を通常のプラグイン
+コマンドログに記録します。スタートアップの失敗でサーバーが停止することはありません。
+
+スタートアップフックは一度限りの初期化コマンドであり、監視されるデーモンではありません。
+フックはプラグインが所有する状態を復元し、必要な Herdr API を呼び出して終了してください。
+たとえば宣言型の Agent ビューを `HERDR_PLUGIN_STATE_DIR` に保存し、スタートアップフックで
+読み込んで再適用できます。
+
+スタートアップフックは通常のランタイムプラグイン環境と
+`HERDR_PLUGIN_EVENT=startup` を受け取ります。インストールプレビューには、自動実行される
+コードを確認できるよう、すべてのスタートアップコマンドが表示されます。
+
+## コマンドと環境
+
+ランタイムコマンドは、プラグインディレクトリを作業ディレクトリとして実行されます。
+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`（スタートアップフックでは `startup`）を受け取り、
+イベントフックはさらに `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`、`popup`、`split`、`tab`、`zoomed` で上書きできます。
+
+`placement = "popup"` は、タイルレイアウトを変更せずにセッションモーダルなターミナルポップアップを開きます。
+マニフェストまたは open リクエストで任意の `width` と `height` を指定できます。
+省略するとデフォルトの半分のサイズになり、数値なら外側のターミナルセル数、`"80%"` のような文字列ならターミナル領域に対する割合になります。
+Escape を含むすべてのターミナル入力を受け取り、コマンドが終了するか `popup.close` リクエストが送られると閉じます。
+最小サイズより小さい寸法は最小値に制限されます。
+
+ペインを常に一時的にしたい場合は、プラグインペインのエントリーポイントに placement を直接宣言します:
+
+```toml
+[[panes]]
+id = "picker"
+title = "Picker"
+platforms = ["linux", "macos"]
+placement = "popup"
+width = "80%"
+height = 20
+command = ["sh", "picker.sh"]
+```
+
+split、tab、zoomed、overlay のプラグインペインは、開いた後は通常の Herdr ペインです。プラグインはソケットや CLI を
+通じて `pane.move`、`pane.swap`、`pane.resize`、`pane.zoom` といった標準のペイン
+API を呼び出せます。ペインがタブやワークスペースをまたいで移動しても、Herdr は
+プラグインペインの所有権を元のペインに結び付けたまま維持します。
+ポップアップは Herdr ペインではなく、セッションに 1 つだけ存在できるリソースです。
+ペイン id を持たず、プラグインのフォーカスコンテキストを変更せず、ペインのライフサイクルイベントを発行せず、pane、layout、永続化、エージェント API に参加しません。
+そのプロセスには `HERDR_PANE_ID` が渡されず、背後のタイルペインは `HERDR_PLUGIN_CONTEXT_JSON` から参照できます。
+Settings、コピーモード、または別の Herdr モーダルが開いている間にポップアップを開くと `ui_busy` が返り、起動後の `plugin.pane.open` は `ok` を返します。
+
+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` も
+読めます。ハンドラーは各プラグイン内でマニフェストの順にチェックされます。
+
+リンクのクリックでプラグインを呼び出すのは、`ui.mouse_capture` が有効な場合だけです。一致するハンドラーが先に実行され、起動に失敗するとエラーを表示して停止します。一致するハンドラーがない場合、外部で開くのは HTTP(S) リンクだけです。キャプチャが無効な場合、外側のターミナルが通常のショートカットと警告で明示的なハイパーリンクを処理します。Windows Terminal の URL 検出の注意点は[マウス操作](/ja/docs/quick-start/#マウスを使う)を参照してください。
+
+## ストレージ
+
+v1 には Herdr が管理するプラグインストレージ API はありません。永続状態が必要な
+プラグインは、自分のファイルやデータベースを持ってください。
+
+## マーケットプレイス
+
+コミュニティ製プラグインは[マーケットプレイス](/plugins/)で探せます。これは
+GitHub トピック `herdr-plugin` が付いており、必須メタデータを解析できる
+`herdr-plugin.toml` が 1 つ以上ある公開 GitHub リポジトリの自動インデックスです。
+プラグインは普通の GitHub リポジトリのままです: 公開して
+`herdr plugin install owner/repo[/subdir]` を共有してください。
+
+プラグインを掲載するには、公開リポジトリに GitHub トピック `herdr-plugin` を追加し、
+デフォルトブランチのルートまたはサブディレクトリにマニフェストを置きます。
+1 つのリポジトリカードに複数のプラグインを掲載できます。インデックスは 30 分ごとに
+更新されます。発見の仕組みは
+[マーケットプレイス](/ja/docs/marketplace/)を参照してください。
@@ -0,0 +1,75 @@
+---
+title: クイックスタート
+description: 最初の Herdr ワークスペースを作成し、永続的なターミナルペインでエージェントを動かします。
+---
+
+Herdr をまだインストールしていない場合は[インストール](/ja/docs/install/)を参照してください。その後、任意のプロジェクトディレクトリから Herdr を起動します:
+
+```bash
+herdr
+```
+
+Herdr はデフォルトのバックグラウンドセッションを起動するか、それにアタッチします。ソケットを管理する必要はありません。デタッチしてもエージェントは動き続けます。
+
+## ワークスペースを作成する
+
+セッションにワークスペースがない場合、Herdr は自動的にひとつ開きます。ワークスペースはタブ、ペイン、エージェントを入れるプロジェクト単位のコンテナです。アクティブなプロジェクトごとに専用のワークスペースを作ってください。そうすることでサイドバーのエージェント状態が読みやすくなります。
+
+## マウスを使う
+
+Herdr はマウスネイティブなので、まずはクリックから始めてください。ペイン、タブ、ワークスペース、エージェントをクリックしてフォーカスします。分割境界をドラッグしてリサイズします。右クリックでコンテキストメニューが開き、ペインの分割やタブの作成ができます。テキストをドラッグ選択するとクリップボードにコピーされます。トークンをダブルクリックすると選択し、2 回目の押下を保持してドラッグすると単語単位で選択を広げられます。どちらもマウスを離すとコピーされます。コピーに Ctrl+C は不要です。
+
+ターミナルが修飾キー付きクリックを Herdr に渡す場合、Ctrl+クリックでペイン内のリンクを開けます。OSC 8 ハイパーリンクと `http://` または `https://` の URL に対応し、折り返されたリンクの先頭や末尾が表示範囲外でも開けます。Ctrl を押しながらリンク上にポインターを移動すると、表示中の部分に下線が付きます。ポインターを外す、ペイン内容が変わる、または Ctrl の解放イベントを受け取ると下線は消えます。一部のターミナルでは、修飾キーの変化はマウス移動時にだけ報告されます。
+
+`ui.mouse_capture = true`（既定値）では、Herdr が Ctrl+クリックを処理します。有効なプラグインがリンクに一致すると、先に実行されます。ハンドラーの起動に失敗するとエラーを表示して停止します。一致しない `http://` と `https://` のリンクは、Herdr クライアントが動くマシンの既定ブラウザーで開きます。その他のリンクには一致するプラグインが必要です。このモードでは明示的なハイパーリンクを外側のターミナルに渡さないため、ラベル付きリンクをネイティブ操作で開けません。macOS の Command+クリックも同様です。
+
+`ui.mouse_capture = false` では、明示的なハイパーリンクを外側のターミナルに渡します。そのターミナルの通常のショートカットと警告が使われ、Herdr のプラグインは実行されません。キャプチャを無効にすると、タブのクリックや分割境界のドラッグなど、Herdr のマウス操作も無効になります。
+
+Windows Terminal は表示テキストから検出した URL を先に開く場合があります。それらを確実にプラグインへ渡すには、Windows Terminal の `settings.json` で `"experimental.detectURLs": false` を設定してください。全プロファイルに適用されます。Herdr はこの設定を変更しません。
+
+`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/) — キーバインド、テーマ、通知、その他すべて。
@@ -0,0 +1,137 @@
+---
+title: セッション状態と復元
+description: Herdr が何をライブで維持し、再起動後に何を復元し、履歴から何をリプレイし、エージェントインテグレーションで何を resume し、アップデート時に何をハンドオフするかを理解します。
+---
+
+Herdr には複数の状態管理経路があります。それぞれが異なる問題を解決します。
+
+## 何が生き残るか
+
+| ケース | プロセスは動き続ける | レイアウトは戻る | 直近の画面は戻る | エージェントの会話は再開する |
+| --- | --- | --- | --- | --- |
+| デタッチと再アタッチ | はい | はい | はい (ライブのターミナルから) | はい (プロセスが止まらないため) |
+| サーバー再起動 | いいえ | はい | ペイン画面履歴が有効な場合のみ | エージェントネイティブのセッション復元がある場合のみ |
+| `--handoff` なしのアップデート | 互換性のあるサーバーは動き続ける。再起動が必要なサーバーは停止/再起動が必要な場合がある | 再起動後は戻る | ペイン画面履歴が有効な場合のみ | エージェントネイティブのセッション復元がある場合のみ |
+| `--handoff` ありのアップデート | 対応する稼働中サーバーではベストエフォート | はい | はい (ハンドオフが成功すればライブのターミナルから) | はい (ハンドオフが成功すればプロセスが動き続けるため) |
+
+以下のセクションでそれぞれの経路を説明します。
+
+## ライブ永続化
+
+通常のデタッチでは Herdr サーバーは動き続けます。ペイン、シェル、エージェント、サーバー、テスト、コマンドプロセスはそのサーバー内で動き続けます。
+
+`ctrl+b q` でクライアントをデタッチします。あとで再アタッチします:
+
+```bash
+herdr
+```
+
+元のプロセスが一度も止まらないため、これが最も強力な永続化経路です。
+
+## スナップショット復元
+
+Herdr サーバーが停止して再起動すると、元のペインのプロセスは失われています。Herdr は保存されたセッションの形を復元します: ワークスペース、タブ、ペイン、cwd、レイアウト、フォーカスです。
+
+スナップショット復元は、動作中のシェル、サーバー、テスト、その他任意のプロセスを保存しません。より強力な復元経路が使えないペインは、保存されたディレクトリで新しいシェルとして戻ってきます。
+
+保存されたディレクトリが使えない場合やシェルを起動できない場合、ペインは消えたりホームディレクトリへ移動したりせず、エラーを表示してレイアウトに残ります。保存されたディレクトリとエージェントのセッション参照は保持されます。ディレクトリやシェル設定を修正してサーバーを再起動すると再試行できます。不要なペインは明示的に閉じて削除できます。
+
+保存時には、OS が取得をサポートしていれば、実行中のシェルのディレクトリを優先します。シェル終了後も最後に確認したディレクトリを保持します。それ以外の環境ではシェルが報告したディレクトリを使用します。
+
+`session.json` を読み込めない、解析できない、または新しい Herdr バージョンが必要な場合、読み込みに失敗した理由をログに記録します。新しいセッションを保存または削除する前に、元のファイルをそのまま `session.json` の隣の `session-backups/` に保存し、復旧用コピーのパスを `persist.backup` として記録します。起動時にファイルがなかった場合も、最初の保存または削除の前に再確認します。これらの読み込み失敗時の復旧用コピーは、通常のスナップショット履歴とは別に管理します。
+
+復旧用コピーは最新の 3 個を保持し、新しいコピーの安全な保存が完了してから古いコピーを削除します。コピーに失敗すると、自動保存時も終了時も元のファイルを変更せず、失敗をログに記録し、次の保存要求時に再試行します。コピーが自動的に復元されることはありません。復旧するには、対象のサーバーを停止し、復旧用ファイルをそのサーバーの `session.json` にコピーしてから再起動します。復旧用コピーにペイン画面履歴は含まれません。
+
+## シャットダウンとスナップショットからの復旧
+
+systemd-logind を使う Linux では、Herdr はホストのシャットダウン予告を受け取り、保存して停止するまで短い遅延を要求します。その後 logind がシャットダウンを進めます。遅延には OS による上限があり、無期限にはブロックしません。logind がない環境、強制終了、電源断、予告前にプロセスが終了した場合には、この保護は使えません。
+
+全プラットフォームで、`session.json` の隣の `session-snapshots/` に最大 48 個のレイアウトスナップショットを保持します。最初に保存したレイアウトは直ちにコピーします。その後の保存や削除では、直前の保存済みレイアウトを最大 15 分に 1 回コピーします。同じ内容は重複保存しません。この間隔はサーバーの再起動後も維持されるため、連続したペイン終了や再起動で古いコピーがすべて押し出されることはありません。直近の変更がコピーに含まれない場合があります。
+
+通常のペイン終了は引き続き `session.json` に反映されます。復旧を促す通知や、古いスナップショットの自動復元はありません。手動で復旧するには:
+
+1. `herdr session list --json` で対象のセッションディレクトリを確認します。
+2. 対象サーバーを停止します。デフォルトは `herdr server stop`、名前付きセッションは `herdr session stop <name>` です。
+3. 現在の `session.json` を別にコピーしてから、`session-snapshots/` 内の選んだファイルを `session.json` にコピーします。ファイルの更新日時で保存時刻を確認できます。
+4. セッションを再起動します。
+
+コピーにはレイアウトとエージェントのセッション参照が含まれますが、実行中のプロセスやペイン画面履歴は含まれません。非公開のセッションデータとして扱ってください。コピーの書き込みに失敗するとログに記録しますが、通常のセッション保存は続行します。
+
+## ペイン画面履歴のリプレイ
+
+ペイン画面履歴は、サーバーの完全な再起動後に直近のターミナル内容を復元します。復元されるのは Herdr が表示できるものであって、元のプロセスではありません。
+
+ペイン出力にはシークレット、トークン、プロンプト、コマンド出力が含まれうるため、これはデフォルトで無効です。設定ファイルで有効にします:
+
+```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 インテグレーションを通じてネイティブセッション参照を報告したペインと、エージェント自身が resume コマンドを報告したペインです。[エージェントに Herdr 対応を追加する](/ja/docs/add-herdr-support/)を参照してください。
+
+クライアントがアタッチしてターミナルサイズとテーマのコンテキストを提供すると、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>` |
+| Grok CLI | `2` | `grok --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>` |
+| Qwen Code | `1` | `qwen --resume <id>` |
+| Letta Code | `1` | `letta --conversation <id>`、または `default:<agent-id>` の場合は `letta --conversation default --agent <agent-id>` |
+| OpenCode | `5` | `opencode --session <id>` |
+| Kilo Code CLI | `1` | `kilo --session <id>` |
+| Hermes Agent | `2` | `hermes --resume <id>` |
+| MastraCode | `1` | `mastracode --thread <id>` |
+
+インストール済みインテグレーションのバージョンは `herdr integration status` で確認できます。古いインテグレーションは `herdr integration install <agent>` で再インストールしてください。
+
+未対応、欠落、無効、重複、または古くなったセッション参照は、保存されたペインディレクトリで通常のシェルとして復元されます。
+
+あるペインにエージェントネイティブのセッション復元が適用される場合、Herdr はそのペインでは保存済みペイン履歴のリプレイではなくエージェントセッションの resume を行います。
+
+## ライブハンドオフ
+
+ライブハンドオフは、稼働中の Herdr サーバーを置き換える必要があるアップデートやリモートアタッチのフローのためのものです。古いサーバーにライブペインを新しいサーバーへ移すよう依頼し、サーバー交換をまたいでペインのプロセスが動き続けられるようにします。
+
+これはスナップショット復元、ペイン履歴リプレイ、エージェントネイティブのセッション復元とは異なります。ハンドオフは現在のプロセスを生かし続けようとします。他の経路は、古いサーバーが停止した後に状態を再構築します。
+
+ハンドオフが保護するのは、ペインの PTY とプロセス、エージェントの識別情報と永続メタデータ、交換後のサーバーに必要なプラグイン/セッション状態など、サーバーが所有する長寿命のセッション状態です。交換境界をまたぐ一時的な協調状態は保持しません。処理中の CLI/API リクエスト、wait、購読ストリーム、クライアントソケット、ペイン間メッセージは中断される可能性があるため、クライアントは再接続して再試行してください。
+
+更新済みの Unix サーバーは、ペインを分割して転送することで 64 個を超えるペインを 1 回のハンドオフで送信できます。送信側サーバーがすでにこの機能を備えている必要があります。古いサーバーからの最初の更新では、引き続き 64 ペインの制限が適用されます。その場合は通常のサーバー再起動が必要になることがあり、ペインのプロセスは終了します。分割転送によって更新のインストール順序や他の互換性要件が変わるわけではありません。
+
+ライブハンドオフは実験的機能で、オプトインです:
+
+```bash
+herdr update --handoff
+herdr --remote workbox --handoff
+```
+
+素の `herdr update` は新しいクライアントをインストールし、エンドポイント世代 1 のサーバーを動かしたままにします。素の `herdr --remote workbox` も、バージョンが違っていても互換性のあるリモートサーバーを動かしたままにします。停止が必要なのは世代 1 より前のサーバーを一度だけ更新するときです。対応する実行中サーバーをペインプロセスを失わず明示的に置き換えたい場合は `--handoff` を使います。
+
+`herdr update --handoff` は Herdr 自身のアップデーターが管理するインストールにのみ適用されます。Homebrew、mise、Nix のインストールはそれぞれのパッケージマネージャーで更新されるため、そこでは `herdr update` は無効化されており、ライブハンドオフは実行できません。
@@ -0,0 +1,771 @@
+---
+title: ソケット API
+description: スクリプト、ツール、コーディングエージェントから実行中の Herdr サーバーを制御します。
+---
+
+Herdr は、実行中のセッションを調査・制御する必要があるスクリプトやエージェント向けに、ローカルソケット API を公開しています。
+
+ほとんどの自動化は CLI ラッパーから始めるべきです。生のソケット API は、直接のリクエスト/レスポンス制御や長寿命のイベント購読が必要なときだけ使ってください。
+
+## インテグレーション層を選ぶ
+
+| 層 | 用途 |
+| --- | --- |
+| エージェントスキル | ペイン内からの Herdr の使い方をコーディングエージェントに教える。 |
+| CLI ラッパー | シェルスクリプト、シンプルなオーケストレーション、人間によるデバッグ。 |
+| 生のソケット API | カスタムツール、プロトコルクライアント、イベント購読者。 |
+
+これらの層は同じ制御面を共有します。
+
+## スキーマ
+
+インストール済み CLI は、その Herdr バイナリに同梱されたソケットプロトコルスキーマを表示できます:
+
+```bash
+herdr api schema
+herdr api schema --json
+herdr api schema --output herdr-api.schema.json
+```
+
+通常の `herdr api schema` は短い概要を表示します。`--json` はツール向けの完全な JSON Schema を表示し、`--output PATH` はそのドキュメントをファイルに書き込みます。スキーマには、生のリクエスト、成功レスポンス、エラーレスポンス、発行イベント、購読イベントが含まれます。
+
+## 制御できるもの
+
+ソケット API では次のことができます:
+
+- ワークスペースの作成、一覧、フォーカス、名前変更、クローズ
+- タブの作成、一覧、フォーカス、名前変更、クローズ
+- ペインの一覧、調査、分割、入れ替え、フォーカス、リサイズ、名前変更、読み取り、クローズ、入力送信
+- 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 agent wait w1:p1 --until 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` |
+| セッション | `session.snapshot` |
+| ワークスペース | `workspace.create`、`workspace.list`、`workspace.get`、`workspace.focus`、`workspace.rename`、`workspace.move`、`workspace.move_block`、`workspace.report_metadata`、`workspace.close` |
+| Worktree | `worktree.list`、`worktree.create`、`worktree.open`、`worktree.remove` |
+| タブ | `tab.create`、`tab.list`、`tab.get`、`tab.focus`、`tab.rename`、`tab.move`、`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` |
+| ポップアップ | `popup.close` |
+| レイアウト | `layout.export`、`layout.apply`、`layout.set_split_ratio` |
+| エージェント | `agent.list`、`agent.get`、`agent.read`、`agent.explain`、`agent.send_keys`、`agent.prompt`、`agent.wait`、`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` |
+
+`agent.wait` はサーバー所有でイベント駆動です。解決したペイン占有者に固定されるため、置換されたエージェントが待機を満たすことはありません。`agent.prompt` は `until` と `timeout_ms` を持つ省略可能な `wait` オブジェクトを受け付けます。これにより、プロンプト送信と待機開始を 1 つのリクエストで行い、別々の呼び出し間の競合を避けられます。解決したエージェントがすでに `blocked` の場合、`agent.prompt` は入力を送信せず、待機も開始せずに `agent_blocked` を返します。
+
+`workspace.move_block` は、順序付きの `workspace_ids` を `before_workspace_id` の前へアトミックに移動します。アンカーを省略するとブロックを末尾へ移動します。id は一意である必要があり、アンカーをブロックに含めることはできません。レスポンスにはサーバーが確定した順序付きワークスペース一覧が含まれます。
+
+`session.snapshot` は、独自のローカルランタイムキャッシュを持つクライアント向けに、一度限りのブートストラップスナップショットを返します。レスポンスには、バージョン/プロトコルメタデータ、フォーカス中のワークスペース/タブ/ペイン id、ワークスペース、タブ、ペイン、タブレイアウト、エージェントの各レコードが含まれます。これは購読ではありません。キャッシュの初期化と復旧では、先に購読を開始し、後述のイベント購読セクションの手順でサーバーから現在の状態を読み取り、キャッシュを照合・更新します。イベントはキャッシュの無効化を知らせるものであり、スナップショットに無条件で再適用できるものではありません。再接続後やキャッシュが古い可能性がある場合は、`session.snapshot` を再度呼び出します。ワークスペースレコードには、関連付けられた worktree の出自情報も含まれます。リポジトリ全体の worktree 検出には引き続き `worktree.list` を使います。
+
+CLI の `herdr api snapshot` は、クライアントやエージェントが簡単にブートストラップできるよう、現在の `session.snapshot` レスポンスを JSON で出力します。
+
+ペイン制御メソッドは `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+` のバインド文字列は受け付けません。
+
+macOS では、`pane.send_input`（`pane run` が使用）と `agent.start` は、コマンドを入力キューに受け入れる前に、ターミナルの現在のカノニカルモードの入力上限を確認します。Enter を含むエンコード済みの行が上限を超える場合、入力全体を拒否します。シェルプロンプトが表示されてから再試行してください。複数の短い行と raw モードの入力は引き続き使用できます。成功応答はキューへの受け入れを示し、コマンドの実行完了を意味しません。この確認は今回の送信だけを対象とし、以前の未完了行を検査したり、キューで待機中にターミナルモードが変わらないことを保証したりするものではありません。
+
+```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` があるときはそのペインを返します。省略時はアクティブなフォーカス中ペインを返します。
+
+ターミナルのスクロール情報を取得できる場合、`PaneInfo` には `scroll` が含まれます:
+
+```json
+{
+  "offset_from_bottom": 12,
+  "max_offset_from_bottom": 240,
+  "viewport_rows": 30
+}
+```
+
+クライアントは `offset_from_bottom == 0` を最下部にいる状態として扱えます。
+
+### ペイングラフィックス
+
+アプリケーションとプラグインは、ペインのターミナル出力を通じて標準の Kitty グラフィックスプロトコルを送信してください。Herdr が対応する外側ターミナルで画像の配置、クリッピング、表示状態を管理します。
+
+外部ソケットのペイン画像オーバーレイ API は削除されました。`pane.graphics.info`、`pane.graphics.set`、`pane.graphics.clear`、`pane.graphics.stream` は利用できず、代替のソケット画像 API もありません。旧サーバーとの内部通信プロトコルの互換性は、これらの公開メソッドを復活させるものではありません。
+
+`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" }
+      }
+    }
+  }
+}
+```
+
+`layout.set_split_ratio` は、タブレイアウト内の既存の分割比率を更新します。レスポンスは、更新済みの移植可能な `layout` を含む `type: "layout_split_ratio_set"` です。
+
+```json
+{"id":"req_ratio","method":"layout.set_split_ratio","params":{"tab_id":"w1:t1","path":[],"ratio":0.6}}
+```
+
+プロセスを起動するメソッドは `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` はタイトルを `ui.window_title` に戻します。レスポンスは `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` も発行します。
+
+リンクされた worktree ワークスペースが開いている親ワークスペースを `workspace.close` で閉じるには、params に `"close_group": true` が必要です。明示的なグループクローズ指定がない場合は `workspace_group_close_required` を返します。明示的なグループクローズは、閉じた各ワークスペースについて `workspace.closed` イベントを 1 件ずつ発行します。
+
+## エージェントビューのクエリ
+
+`agent.view.set` は、組み込みの Agents ビューに一つの一時的な宣言型プロジェクションを
+設定します。エージェントの情報や現在の UI コンテキストが変わるたびに再評価されます。
+展開・折りたたみサイドバー、モバイルの Agents リスト、マウスターゲット、番号付き
+フォーカス、前後のエージェントへの移動順を制御します。`agent.list`、通知、検出、
+グローバルな要対応件数は変更しません。
+
+現在表示中の Space にいるエージェント、または別の場所で対応が必要なエージェントを
+表示し、要対応度と直近の状態遷移で並べ替える例です:
+
+```json
+{
+  "id": "view_set",
+  "method": "agent.view.set",
+  "params": {
+    "source": "plugin:example.agent-views",
+    "label": "focus",
+    "filter": {
+      "op": "any",
+      "filters": [
+        {
+          "op": "eq",
+          "field": "workspace_id",
+          "value": {"context": "current_workspace_id"}
+        },
+        {
+          "op": "in",
+          "field": "status",
+          "values": ["blocked", "done"]
+        }
+      ]
+    },
+    "sort": [
+      {"field": "attention", "order": "desc"},
+      {"field": "state_change_seq", "order": "desc"}
+    ]
+  }
+}
+```
+
+フィルターノードの `op` には `all`、`any`、`not`、`eq`、`in`、`exists` を使います。
+組み込みフィールドは `status`、`workspace_id`、`tab_id`、`pane_id`、`agent`、
+`seen`、`state_change_seq` です。プラグインが報告したペインメタデータを絞り込むには、
+フィールドとして `{"token":"name"}` を使います。値には文字列、真偽値、符号なし整数、
+またはコンテキストオブジェクトを指定できます。コンテキスト値は
+`current_workspace_id` と `current_tab_id` で、対応する ID フィールドとの比較にだけ
+使えます。保存済みマシンに接続するクライアントでは、選択中サーバーのビューを統合エージェント一覧に適用します。現在のワークスペースとタブのコンテキストには選択中のマシンも含まれるため、別マシンの同じ ID は一致しません。一方、`status` が `blocked` かどうかなど独立したフィルター条件は、接続中のすべてのマシンに一致できます。有効な status は `idle`、`working`、`blocked`、`done`、`unknown` です。
+`done` は idle かつ未確認の状態を表します。
+
+ソートフィールドは `workspace_order`、`tab_order`、`pane_order`、`attention`、
+`status`、`agent`、`seen`、`state_change_seq`、または `{"token":"name"}` です。
+ソートは安定しており、指定順に評価され、`asc` または `desc` を受け付けます。値がない
+項目は値がある項目の後に残ります。`sort` を省略すると既存の
+`ui.agent_panel_sort` ポリシーが有効です。カスタムソートは設定を書き換えず、一時的に
+そのポリシーを置き換えます。
+
+`source` は所有者を識別します。プラグインは `plugin:<HERDR_PLUGIN_ID>` を使います。
+所有元のプラグインが存在しないか無効な場合、Herdr は設定を拒否します。他の呼び出し元は
+独自の非 `plugin:` source を使えます。設定に成功すると以前のビューはアトミックに
+置き換えられます。ビューは clear または置換されるか、所有プラグインが disable、unlink、
+uninstall されるか、サーバーが終了するまで有効です。永続的な動作が必要なプラグインは、
+クエリを `HERDR_PLUGIN_STATE_DIR` に保存し、`[[startup]]` フックから再適用してください。
+
+無条件で clear するか、指定した source がまだ所有している場合だけ clear できます:
+
+```json
+{"id":"view_clear","method":"agent.view.clear","params":{}}
+{"id":"view_clear_owned","method":"agent.view.clear","params":{"source":"plugin:example.agent-views"}}
+```
+
+source が一致しない場合、アクティブなビューは変わりません。set と clear のレスポンスは
+`type: "agent_view"` で、`active`、`source`、任意の `label` を報告します。
+
+## プラグイン 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`、`popup`、`split`、`tab`、`zoomed` でマニフェストを上書きできます。overlay と popup はアクティブなタイルペインを起動コンテキストとして使います。ポップアップターミナルはセッションモーダルで、タブレイアウトを変更しません。任意の `width` と `height` は、外側のサイズをターミナルセル数または `"80%"` のような割合で指定します。省略した寸法はデフォルトでターミナルの半分になり、小さすぎる値は最小サイズに制限されます。ポップアップはペイン id を持たず、`pane.*` とエージェント API の対象外で、ペインのライフサイクルイベントを発行せず、プラグインのフォーカスコンテキストを背後のタイルペインに維持し、そのプロセスへ `HERDR_PANE_ID` を渡しません。起動は `ok` を返し、`popup.close` はアクティブなポップアップを閉じ、ポップアップがない場合は `popup_not_open` を返します。split と zoomed は既存のペインを対象とし、tab はワークスペースを対象にできます。split、tab、zoomed、overlay は通常の Herdr ペインとして振る舞い、`plugin.pane.focus` と `plugin.pane.close` は引き続きそれらのペインに作用します。
+
+## ソケットトランスポート
+
+Herdr はローカルソケット上の改行区切り JSON を使います。Unix では Unix ドメインソケットです。Windows では名前付きパイプです。
+
+1 行につき 1 リクエストを送ります:
+
+```json
+{"id":"req_1","method":"ping","params":{}}
+```
+
+成功レスポンスは同じ `id` を含みます:
+
+```json
+{"id":"req_1","result":{"type":"pong"}}
+```
+
+JSON のデコードまで到達したリクエスト行では、メソッドやパラメーターが無効な場合も含め、エラーレスポンスにもリクエストの `id` がそのまま含まれます。JSON が無効、またはトップレベルの文字列 `id` を一意に特定できない場合、エラーレスポンスは空の `id` を使います。無効な UTF-8 などのトランスポートエラーでは、レスポンスを返さずに接続を閉じる場合があります。
+
+イベント購読は、最初のレスポンスの後も接続を開いたままにします。
+
+## ソケットパス
+
+デフォルトのソケットは 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"
+  }
+}
+```
+
+`state` は意味的です。wait、通知、ロールアップに影響します。表示専用の値はメタデータで別に報告します。
+
+セッションのみの公式インテグレーションは、`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 サーバーの再起動後に報告元の現在のセッションを再開するコマンドを、省略可能な `resume_argv` 配列で受け付けます。配列は最大 64 要素、合計 8 KiB までです。最初の要素はパスではなく単純なコマンド名でなければならず、どの要素にもアポストロフィや制御文字を含めることはできません。無効な値は `invalid_resume_argv` で失敗し、その報告は適用されません。カスタムエージェントは、コマンドを付ける前に `pane.report_agent` でペインを保持している必要があり、そうでない場合は `resume_not_accepted` で失敗します。Herdr は同じ `source` と `agent` がペインを保持している間だけコマンドを保持し、そのエージェントに対する Herdr 組み込みの resume コマンドより優先します。古い Herdr はこのフィールドを無視します。
+
+```json
+{
+  "id": "req_3",
+  "method": "pane.report_agent_session",
+  "params": {
+    "pane_id": "w1:p1",
+    "source": "custom:my-agent",
+    "agent": "my-agent",
+    "agent_session_id": "...",
+    "resume_argv": ["my-agent", "--resume", "..."]
+  }
+}
+```
+
+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 のままです。
+
+`PaneInfo` と `AgentInfo` は、任意の `terminal_title` と `terminal_title_stripped` フィールドを公開します。`terminal_title` は、安全性のための正規化を行った最新の OSC 0/2 タイトルです。`terminal_title_stripped` は、先頭にある認識済みのアクティビティまたはスピナーのグリフ 1 つと、それに続く空白を除去します。これらはサーバーが所有する値で、コールドリスタートをまたいで保持されず、メタデータの `title` や意味的なエージェント状態から独立しています。
+
+ユーザーフックが 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",
+    "state_labels": {
+      "working": "refactoring auth",
+      "idle": "ready",
+      "done": "review ready"
+    },
+    "tokens": {
+      "summary": "refactor auth",
+      "model": "opus"
+    },
+    "ttl_ms": 3600000
+  }
+}
+```
+
+メタデータ報告は表示専用です。有効なメタデータは、ペインのタイトル、表示されるエージェント名、可視の状態ラベル、任意の名前付きトークンを上書きできます。`working`、`blocked`、`idle`、wait、通知、ロールアップは引き続き意味的な状態から得られます。エージェントネイティブのセッション復元は、保存された公式セッション参照から得られます。`agent` は表示フィールドを権威あるエージェントラベルに対して保護する任意のガードで、`applies_to_source` も表示フィールドをアクティブなライフサイクル権威ソースに対して保護します。これらのガードはトークンパッチには適用されません。トークンのクリアと TTL の更新は報告側が管理します。表示名を変えるには `display_agent` を使います。`state_labels` のキーは `idle`、`working`、`blocked`、`done`、`unknown` のいずれかでなければなりません。
+
+トークンマップはリソースごとのパッチです。文字列はキーを設定し、JSON の `null` はクリアし、省略したキーは変わりません。最後に受理された更新が優先されます。任意の TTL は、その報告で更新した各トークンキーに個別に適用されます。ペイントークンは pane と agent の get/list 応答で公開され、エージェントサイドバー行では `$name` として描画できます。1 回の報告で指定できるトークンキーは最大 16 個、ペインまたはワークスペースが保持できるキーは最大 32 個です。トークン名は 1〜32 文字の ASCII 英数字、アンダースコア、ハイフンに限られます。
+
+ワークスペーストークンも同じ規約を使います:
+
+```json
+{"id":"req_3","method":"workspace.report_metadata","params":{"workspace_id":"w1","source":"user:jj","tokens":{"jj_status":"2 changes","old":null},"ttl_ms":5000}}
+```
+
+workspace の get/list 応答は結果の `tokens` マップを公開し、スペースサイドバー行では `$jj_status` のような値を描画できます。変更と TTL の失効は、最新のワークスペーススナップショットを含む `workspace.metadata_updated` を発行します。このメタデータイベントは API 購読者に届きますが、プラグインイベントフックは実行しません。
+
+表示テキストは保存前に正規化されます。Herdr は前後の空白を取り除き、制御文字を除去し、`title`、`display_agent`、各状態ラベル、トークン値を 80 文字に制限します。正規化後に空になったトークン値は、そのキーをクリアします。
+
+`source` と `applies_to_source` はソース識別子です。80 文字以下で、ASCII の英字、数字、コロン、ドット、アンダースコア、ハイフンのみを含められます。
+
+短寿命のメタデータには `ttl_ms` を使ってください。`1` から `86400000` ミリ秒の間でなければなりません。置き換え・クリア・ペインまたはワークスペースのクローズまで残るべきメタデータでは省略します。表示フィールドは従来どおりソース単位で失効し、呼び出しで更新した各トークンには個別の期限が設定されます。トークンメタデータはサーバー再起動後に復元されません。
+
+フックが順不同で更新を送る可能性がある場合は `seq` を使ってください。同じ `source` について、最後に受理されたシーケンス以下のシーケンス番号を持つ報告は、API には受理されますがペイン状態には無視されます。ペインまたはワークスペースが存続する間、シーケンス付きトークン報告を送れる異なるソースは最大 32 個です。クリアや失効でもそのソース枠は解放されません。
+
+## イベント購読
+
+長寿命のストリームが必要なときはイベントを購読します:
+
+```json
+{
+  "id": "sub_1",
+  "method": "events.subscribe",
+  "params": {
+    "subscriptions": [
+      { "type": "pane.agent_status_changed", "pane_id": "w1:p1", "agent_status": "blocked" }
+    ]
+  }
+}
+```
+
+最初のレスポンスは購読の確認応答です。以降の行はプッシュされるイベントです。
+すべての項目が有効でなければなりません。参照先ペインが 1 つでも存在しない場合、Herdr はリクエスト全体をエラーで拒否し、接続を閉じます。他の項目が購読されたと仮定せず、ペイン一覧を更新して再試行してください。
+ライフサイクルイベントの購読はリクエストが受理された時点から始まり、それ以前に保持されていたイベントは再生しません。
+
+ライフサイクルとエージェント状態のイベントは、各購読内の順序を保った上限付きのバッチで送信されます。イベント履歴は永続ログではありません。購読の初期化中も含め、購読者が保持範囲より遅れた場合、サーバーは元のリクエスト `id` と `error.code: "events_lost"` を含むエラーレスポンスを送り、その購読接続を閉じます。欠落したイベントを通知せずに配信を続けることはありません。他のクライアント接続には影響しません。履歴はイベント種別間で共有されるため、失われたイベントが購読条件に一致しなかった可能性があっても、保持範囲を超えたことを通知します。
+
+`events_lost` を受け取ったら、キャッシュを古い状態として扱います。新しい購読を開始して `subscription_started` を待ち、読み取りを続けながら別の接続で `session.snapshot` を取得してください。サーバーの現在の状態でキャッシュを照合し、スナップショットでキャッシュ全体を置き換えます。イベントはキャッシュの無効化通知として扱い、再取得の契機にします。取得は直列に行い、取得中にイベントが届いた場合は完了後に再取得してください。
+
+スナップショットとイベントに共通のシーケンス境界はありません。順序が保証されるのは各購読項目内のみで、項目間やスナップショットとの前後関係は保証されません。バッファしたイベントの内容をスナップショットへ無条件に再適用しないでください。復旧できるのは現在の状態であり、失われたイベント履歴ではありません。再び `events_lost` を受け取った場合は、再購読して状態を照合し直します。読み取りが遅いクライアントでは、読み取り速度を上げるかイベントの負荷を減らす必要があります。
+
+ワークスペースのイベント購読には `workspace.created`、`workspace.updated`、`workspace.metadata_updated`、`workspace.renamed`、`workspace.moved`、`workspace.reordered`、`workspace.closed`、`workspace.focused` があります。`workspace.metadata_updated` はプラグインイベントフックを実行せずにトークン変更と TTL 失効を報告します。その他のワークスペースイベントは Herdr の UI/ランタイムのライフサイクルを記述します。ワークスペースが worktree グループに属している場合、`workspace.created` は任意の `workspace.worktree` 出自情報を含みます。`workspace.moved` は、移動した `workspace_id`、要求された `insert_index`、更新済みの順序付き `workspaces` リストを含みます。`workspace.reordered` は、アトミックに移動した `workspace_ids`、省略可能な `before_workspace_id`、サーバーが確定した順序付き `workspaces` リストを含みます。削除前に Herdr がまだ識別できる場合、`workspace.closed` は最終的な `workspace` スナップショットを含みます。
+タブのイベント購読には `tab.created`、`tab.closed`、`tab.focused`、`tab.renamed`、`tab.moved` があります。`tab.moved` は、移動した `tab_id`、`workspace_id`、要求された `insert_index`、そのワークスペースの更新済みの順序付き `tabs` リストを含みます。
+ペインのイベント購読には `pane.created`、`pane.updated`、`pane.closed`、`pane.focused`、`pane.moved`、`pane.exited`、`pane.agent_detected`、`pane.output_matched`、`pane.agent_status_changed`、`pane.scroll_changed` があります。`pane.focused` は、このサーバーに接続した任意のクライアントでの手動ペイン選択も報告します。他のクライアントの表示は移動させず、ペイロードにクライアントの識別情報は含みません。選択済みのペインを再度選んでも発行しません。ターミナルタイトルの変更は `pane.updated` を発行することがありますが、生のタイトルでスピナーだけが変化し、`terminal_title_stripped` が変わらない場合は発行しません。`pane.scroll_changed` は 1 つの `pane_id` を対象とし、Herdr がスクロールスナップショットの変化を検出するたびに `pane_id`、`workspace_id`、現在の `scroll` 情報を発行します。
+レイアウトのイベント購読には `layout.updated` があります。このイベントは 1 つのタブについて更新済みの `PaneLayoutSnapshot` を運びます。`session.snapshot` でキャッシュを管理するクライアントは、このイベントを契機にサーバーから対象のレイアウトを再取得してください。遅れて届いたペイロードは、最新のスナップショットより古い可能性があります。
+
+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 agent wait w1:p1 --until done
+herdr agent wait w1:p1 --until 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 UI は、ローカルサーバーと SSH サーバーに安定したエンドポイント世代を使います。クライアントとサーバーのビルドが一致する必要はありません。接続時にコアのスナップショット、画面、入力、blob コーデックを合意し、サーバーが対応 API メソッドと任意の能力を通知します。保存済み SSH マシンには、選択中のマシンだけがペイン画面を送信するための `surface_interest` と、通信のない接続の障害を検知する `health_check` が必要です。未対応のサーバーは明示的に更新するまで Attention になります。詳しくは[マシンへの接続](/ja/docs/connecting-machines/)を参照してください。メソッドがない場合は、そのサーバー上の該当アクションだけを無効にしてクライアント側通知を表示します。拒否やタイムアウトも接続を終了せず通知します。エンドポイント世代 1 より前のサーバーだけは最後の 1 回の更新が必要です。
+
+番号付きバイナリプロトコルは、直接ターミナル接続やライブハンドオフなど、同一インストール内の内部操作に残ります。異なるビルド間でそれらを使う前に `ping` または `herdr status` を確認してください。JSON API クライアントは未知のフィールドを無視し、未対応メソッドを通常のエラーとして扱う必要があります。
@@ -0,0 +1,120 @@
+---
+title: トラブルシューティング
+description: インストール、ターミナル入力、セッション、キーバインド、リモート接続の一般的な問題を診断します。
+---
+
+まずバージョンとセッション状態を確認します:
+
+```bash
+herdr -V
+herdr status
+```
+
+OS、外側のターミナル名とバージョン、ローカルまたはリモートのどちらか、tmux を使用しているかも記録してください。
+
+## Windows で CJK IME の UI 位置がずれる、またはカーソルがちらつく
+
+Herdr は、ConPTY ベースのマルチプレクサーによる画面再描画中にネイティブカーソルがちらついたり、ジャンプしたり、古い位置を表示したりすることを避けるため、ネイティブ Windows と WSL ではデフォルトでセル描画カーソルを使います。セル描画カーソルは、韓国語、日本語、中国語 IME の変換中テキストや候補 UI が使用するネイティブカーソルの基準位置を提供できません。
+
+IME の変換中テキストや候補ウィンドウが誤った位置に表示される場合は、ネイティブカーソルを有効にしてください:
+
+```toml
+[ui]
+host_cursor = "native"
+```
+
+ネイティブモードでは IME の基準位置が正しくなりますが、出力中にカーソル表示が乱れることがあります。視覚的に安定したカーソルへ戻すには `host_cursor = "drawn"` を設定するか、設定を削除して Windows のデフォルトを使ってください。現在の制限については [Windows サポート](/ja/docs/windows-beta/) を参照してください。
+
+## 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/herdrdev/herdr/issues/1116) を参照してください。現在のターミナルでも発生する場合は、正確なバージョンと Herdr の外でも発生するかを報告してください。
+
+## Option+Left または Option+Right を押すと `;3D` または `;3C` が入力される
+
+ターミナルは一般に、Alt+Left と Alt+Right を標準の修飾付き矢印シーケンス `ESC[1;3D` と `ESC[1;3C` として送信します。macOS では、まず外側のターミナルで Option を Alt として扱うよう設定する必要があります。シェルがこれらのシーケンスを割り当てていない場合、zsh は残りの文字を `;3D` または `;3C` と表示することがあります。これは kitty、Alacritty、その他のターミナルで発生する可能性があります。Herdr と tmux はどちらも元の修飾付き矢印入力を保持します。
+
+すべてのターミナルとネストしたシェルで修飾付き矢印を単語移動として使う場合は、zsh のバインドを明示的に追加します:
+
+```zsh
+bindkey $'\e[1;3D' backward-word
+bindkey $'\e[1;3C' forward-word
+```
+
+kitty の外では動作するのに Herdr 内では動作しないことがあります。これは kitty の自動 zsh インテグレーションが、kitty が直接起動したシェルにだけこれらのバインドを追加し、ターミナルマルチプレクサーが起動したシェルには追加しないためです。kitty の[手動シェルインテグレーション手順](https://sw.kovidgoyal.net/kitty/shell-integration/#manual-shell-integration)に従うか、シェルへ届く前に `kitty.conf` でキーを割り当ててください:
+
+```text
+map alt+left send_text all \x1bb
+map alt+right send_text all \x1bf
+```
+
+ターミナルアプリケーションが Alt+Left と Alt+Right を直接使用する場合があるため、Herdr は修飾付き矢印を意図的に書き換えません。調査の詳細は [Herdr issue #1370](https://github.com/herdrdev/herdr/issues/1370) を参照してください。
+
+## Herdr を更新したのに実行中のセッションが古い
+
+バイナリを更新しても、互換性のある実行中サーバーは置き換わりません。Herdr を開き直せば更新済みクライアントを使えます。サーバー側の新機能も必要な場合だけ、`herdr status` で確認してからセッションを停止し、Herdr を再起動します:
+
+```bash
+herdr server stop
+herdr
+```
+
+サーバーを停止するとペインのプロセスも終了します。名前付きセッションでは `herdr session stop <name>` を使います。更新機能、パッケージマネージャー、ライブハンドオフについては[インストール](/ja/docs/install/#update)を参照してください。
+
+## macOS の Herdr 内で Keychain を使うツールが失敗する
+
+Herdr のペインからサーバーの起動コンテキストを確認します:
+
+```bash
+launchctl managername
+```
+
+自動起動された macOS サーバーでは `Background` は正常で、この表示だけでは Keychain の問題を意味しません。Keychain にアクセスできず、サーバーを SSH やバックグラウンドジョブから起動していた場合は、停止して通常の GUI ターミナルから Herdr を再起動してください:
+
+```bash
+herdr server stop
+herdr
+```
+
+サーバーを停止するとペインのプロセスも終了します。Herdr のペインは長時間動作するサーバーの macOS 起動コンテキストを継承するため、SSH やバックグラウンドジョブから起動されたサーバーは対話型 Keychain サービスにアクセスできないことがあります。詳細は [Herdr issue #966](https://github.com/herdrdev/herdr/issues/966) を参照してください。
+
+## macOS のログアウト後に SSH や DNS が失敗する
+
+自動起動された macOS サーバーはユーザー単位のサービスコンテキストを使用するため、ログアウトしてもペインと macOS サービスの接続が無効になりません。明示的な `herdr server` 起動では、呼び出し元のコンテキストを維持します。
+
+古いサーバーはログアウト後も動作し続ける一方、ユーザー情報の検索や DNS が使えなくなることがあります。症状には `No user exists for uid 501`、`Could not get manager name.`、`curl: (6) Could not resolve host` などがあります。再ログインだけでは修復されません。対象セッションを停止し、新しいログインの GUI ターミナルから Herdr を起動してください。実行中のペインプロセスは終了しますが、保存されたセッション配置は復元されます。ライブハンドオフは元のサーバーのサービスコンテキストと既存のペインプロセスを維持します。そのため、古いサーバーにこの修正を適用するにはセッションの完全な再起動が必要です。ハンドオフでは継承したコンテキストを修復できません。
+
+新しく起動したサーバーでも問題が起きる場合は、`herdr-server.log` の `could not select persistent user service context` を確認してください。必要な macOS API が利用できない場合、Herdr は継承したコンテキストを維持します。[Herdr issue #4100](https://github.com/herdrdev/herdr/issues/4100) を参照してください。
+
+## `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)を参照してください。
@@ -0,0 +1,162 @@
+---
+title: Windows サポート
+description: ネイティブ Windows 対応、サポートされるワークフロー、既知の制限。
+---
+
+ネイティブ Windows 対応は正式に提供されています。
+
+Windows 上の Herdr は、Herdr が本来前提としていた Unix の PTY モデルではなく、ConPTY と Windows のプロセス/ランタイム挙動を使います。主要なワークフローの多くはサポートされていますが、一部の機能は Linux/macOS と異なるか、プラットフォームに依存します。残っている差を埋める間、Windows 固有の修正がより多く提供されることがあります。
+
+Windows に Herdr をネイティブインストールするには PowerShell を使います:
+
+```powershell
+powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
+```
+
+エンドポイントセキュリティによってこのファイルレス PowerShell コマンドがブロックされる場合は、コマンドプロンプトを開いて次を実行します：
+
+```cmd
+curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del install.cmd
+```
+
+Windows ビルドは安定版とプレビューの両方のアップデートチャンネルで提供されます。新規インストールはデフォルトで安定版を使い、通常の利用には安定版を推奨します。既存のプレビューインストールは、`herdr channel set stable` を実行するまでプレビューに残ります。古いプレビュービルドでこのコマンドが拒否される場合は、プレビューのまま一度 `herdr update` を実行してから再試行してください。プレビューでは `master` からの新しく検証の少ない修正を受け取れますが、リグレッションが起きる可能性があります。そのトレードオフを望む場合に限り、`herdr channel set preview` でオプトインしてください。
+
+インストーラーはリリースを `%USERPROFILE%\.herdr\packages\standalone\releases` に保存し、有効なバージョン付きリリースディレクトリを PATH に追加し、`%LOCALAPPDATA%\Programs\Herdr\bin` を安定した互換エイリアスとして維持します。また、実行中のプロセスがアップデートを妨げないよう少数の古いリリースを保持します。
+
+内部テスト向けに、`HERDR_MANIFEST_URL` でインストーラーを Herdr の安定版/プレビューマニフェストではなくカスタムマニフェストに向けられます。カスタムプレビューマニフェストでは `HERDR_CHANNEL=preview` も設定してください。
+
+## Windows でサポート
+
+| 機能 | 状況 |
+| --- | --- |
+| ローカル永続セッション | サポート済み |
+| ConPTY によるネイティブペイン | サポート済み |
+| Windows Terminal / PowerShell アプリからのアタッチ | サポート済み |
+| Linux/macOS/Windows ホストへの `herdr --remote` と保存済み SSH マシン | サポート済み。対話的なアタッチとマシン追加では確認後に Windows パッケージをインストール・更新できます。バックグラウンド再接続ではインストール済みパッケージだけを探します |
+| リモートクリップボード画像と画像ファイルのドロップ | サポート済み |
+| `cmd.exe` ペイン | サポート済み |
+| ネイティブのキーボード/マウス入力 | サポート済み |
+| 起動時 cwd とワークスペースラベル | サポート済み |
+| ペイン起動時の cwd | サポート済み |
+| エージェントコマンドの発見 | サポート済み |
+| 対応済みエージェントのセルフレポートインテグレーション | サポート済み |
+| エージェントのプロセスツリー検出 | サポート済み |
+| 既知の cwd からの Git/worktree 検出 | サポート済み |
+| システム通知と MP3 サウンド | サポート済み |
+| プラグイン | プレビュー |
+| ペイン画面履歴 | サポート済み |
+| ネストされた起動のオーバーライド | サポート済み |
+
+ローカル永続セッションは、クライアントをデタッチした後やターミナルウィンドウを閉じた後も動作し続けます。Windows OpenSSH から起動したサーバーとペインプロセスもログアウト後に存続します。再接続するには `herdr` をもう一度実行してください。
+
+管理者権限の Windows サーバーは、既定では管理者クライアントを必要とします。管理者権限の SSH ログインから起動した場合も同じです。通常権限のサーバーには、同じアカウントの通常・管理者クライアントの両方が接続できます。接続してもサーバーの権限は変わりません。
+
+管理者セッションを通常クライアントと意図的に共有する場合は、次を設定します:
+
+```toml
+[server]
+allow_unelevated_clients = true
+```
+
+この Windows 専用設定は既定では無効で、自動起動を含む新しいサーバーの起動時に適用されます。設定の再読み込みでは実行中サーバーの接続権限は変わりません。代わりに管理者ターミナルで `herdr server --allow-unelevated-clients`（名前付きセッションでは `herdr --session <name> server --allow-unelevated-clients`）を使うと、そのサーバープロセスだけで共有できます。このフラグは設定が false でも共有を有効にします。
+
+どちらも同じアカウントの通常権限プロセスによる管理者ペインの操作を許可します。他のアカウントは引き続き接続できません。設定で有効にしない限り、再起動後もフラグを指定する必要があります。既存サーバーは更新版で停止・再起動するまで以前の接続ポリシーを維持します。停止するとペインも閉じます。設定と復旧ファイルのアカウント単位の権限は変わりません。
+
+Windows のエージェントプロセス検出は、ペインのシェルの子孫プロセスをスキャンし、npm/Node や Git Bash のプロセスチェーンを含む直接のエージェントと一般的なコマンドラッパーを認識します。Git Bash から起動したエージェントはエミュレートされた `exec` 境界を越えて追跡されますが、Unix のフォアグラウンドプロセスグループ検出と同じものではありません。
+
+Windows でインテグレーションをインストールできるのは、現在 Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、OpenCode、Kilo Code CLI、Droid、Kimi Code CLI、Qoder CLI、Antigravity CLI です。利用可能な対象は Unix より少なく、インストール形式が Windows で未対応のインテグレーションは表示されないか拒否されます。
+
+プラグインは、プレビューとしてマニフェストのプラットフォームに `windows` をサポートします。GitHub インストール、ローカルリンク、ビルドコマンド、アクション、イベント、プラグインペインは Windows ではベストエフォートです。コマンドは argv 形式で Windows 互換である必要があります。`npm`、`bun`、`node` のような Node パッケージの shim は `PATH` にあれば動作するはずですが、`sh` や Bash を使う Unix 専用の例には Windows 向けの代替が必要です。プラットフォームフィルターは、未サポートのビルドコマンドをスキップし、未サポートのアクションやペインには `platform_unsupported` を返します。
+
+## 部分的なサポート
+
+| 機能 | 状況 |
+| --- | --- |
+| シェルで `cd` した後のライブ cwd | 部分的 |
+| シェルインテグレーション/OSC7 によるライブ cwd | サポート済み |
+| ローカルペインのエージェントへのクリップボード画像貼り付け | ターミナル/エージェント依存 |
+| CJK IME の変換候補位置 | 部分的 |
+| プレフィックス入力ソース切り替え (韓国語 IME) | 部分的 |
+| Kitty graphics のレンダリング | ターミナル依存 |
+| ホストカーソル描画 | 部分的 |
+
+Herdr はペインを正しいディレクトリで起動でき、Herdr を起動したディレクトリから最初のワークスペースを作成できます。起動後の PowerShell のディレクトリ変更は別問題です: Herdr が調べられるプロセスのフィールドは、その後の論理的な `cd` の変化を確実には追跡しません。ライブ cwd の報告には Herdr インテグレーションかプロンプトのシェルインテグレーションを使ってください。
+
+`herdr --remote` では、設定されたリモート画像貼り付けキーが Windows のクリップボード画像を読み取り、リモートホストへ転送します。Windows Terminal にローカル画像ファイルをひとつドロップした場合も、そのファイルを転送してリモート側のパスを貼り付けます。
+
+プレフィックス入力ソース切り替えは、韓国語 IME 向けのオプトイン実験機能として利用できます。プレフィックスコマンドが有効な間はハングル入力を英語に切り替え、終了後に以前のモードへ戻します:
+
+```toml
+[experimental]
+switch_ascii_input_source_in_prefix = true
+```
+
+その他の Windows IME はまだこのオプションに対応していません。[設定](/ja/docs/configuration/#プレフィックス入力ソースの切り替え)を参照してください。
+
+Windows 上の一部のエージェントは `ctrl+v` を受け取り、クリップボード画像を直接読み取れます。Herdr 自身のクリップボード画像リーダーはローカルのネイティブ Windows ペインには配線されていないため、エージェント自身による画像貼り付けはターミナルとエージェントに依存します。`alt+v` などエージェントの画像貼り付けショートカットによって、Herdr が管理するローカルクリップボードブリッジが追加されるわけではありません。リモートクリップボード画像ブリッジは、Linux/macOS/Windows ホストへの `herdr --remote` で別途サポートされます。
+
+Kitty graphics はデフォルトで有効で、外側のターミナルに依存します。Herdr は他のプラットフォームと同様に Windows でも Kitty graphics protocol の出力を送ります。この経路は Windows の WezTerm から WSL 内の Herdr をホストする構成で動作確認されていますが、ネイティブ Windows のターミナルと ConPTY の組み合わせはすべて検証済みではありません。Windows Terminal は Herdr が使う Kitty graphics 経路を提供しません。外側のターミナルがグラフィックス出力を正しく扱えない場合は、`[terminal].kitty_graphics = false` に設定してください。
+
+## 既知の注意点
+
+### カーソル描画
+
+Herdr はネイティブ Windows のペインに ConPTY を使用します。現在の Windows のターミナルカーソル処理では、マルチプレクサーが画面を再描画している途中のカーソル位置が表示されることがあります。そのため、出力中にネイティブカーソルがちらついたり、ジャンプしたり、古い位置に一瞬残ったりします。この挙動は他のネイティブ Windows ターミナルマルチプレクサーや、VT カーソル位置を直接連続更新するテストでも再現するため、ネイティブカーソルの挙動を維持したまま Herdr 側で完全に解消することはできません。
+
+視覚的な安定性を優先するため、デフォルトの `host_cursor = "auto"` はネイティブ Windows と WSL で Herdr のカーソルを端末セルの内容として描画します。それ以外の Linux と macOS クライアントでは、引き続きネイティブの端末カーソルを使います。Windows の描画カーソルは安定していて点滅しませんが、外側ターミナルのネイティブな点滅、形状、カーソル色は反映されません。
+
+描画カーソルは、Windows が IME の変換中テキストや候補ウィンドウの位置決めに使う実際のカーソルではありません。そのため、韓国語、日本語、中国語 IME の UI が誤った位置に表示されることがあります。この問題が発生する場合は、外側ターミナルのカーソルを有効にしてください:
+
+```toml
+[ui]
+host_cursor = "native"
+```
+
+ネイティブモードでは IME の基準位置が正しくなりますが、出力中にカーソルのちらつき、ジャンプ、古い位置の残像が再び発生することがあります。これは現在の Windows 対応における互換性上のトレードオフです。
+
+### キーボードとマウス
+
+Windows のターミナルは、修飾キー付きのキーをすべて同じ形で報告するわけではありません。Herdr は Windows Terminal と Windows 上の Alacritty でマウス報告と `ctrl+j` を保持します。ネイティブ Windows の入力経路では、物理キーの押下、リピート、解放、単独の Escape、`shift+enter` もデフォルトの ConPTY ペインまで保持されます。ただし修飾キーは、外側のターミナルが区別可能なキーイベントとして報告する必要があります。`shift+enter` が通常の Enter として報告された場合、Herdr が転送できるのも通常の Enter だけです。
+
+古い Windows 10 ビルドのシステム ConPTY は、Kimi や Pi などのエージェントが使用する Kitty キーボードプロトコルのシーケンスを失うため、Windows パッケージには Microsoft の最新のアプリローカル ConPTY ランタイムが含まれます。バンドル版ランタイムとの互換性問題を診断する場合に限り、Herdr を起動する前に `HERDR_WINDOWS_CONPTY=system` を設定してください。
+
+## コピーと貼り付け
+
+Herdr のペインテキストコピーは Windows で動作します。ペイン内でテキストをドラッグ選択すると Herdr 経由でコピーされます。
+
+テキストの貼り付けには Windows Terminal で `ctrl+shift+v` を使ってください。複数行テキストの貼り付けはブラケット付きなので、シェルやエージェントのプロンプトは各行を個別に送信せず、ひとつの貼り付けとして受け取ります。`shift` を押しながら右クリックすると、クリックを Herdr に送らずに外側ターミナルの貼り付けアクションを使えます。
+
+Windows クライアントは、WezTerm が完全な Win32 文字の押下・解放ペアを生のペーストマーカーで囲んだ場合にもテキストを復元します。通常のテキストが混在する場合や不完全なレポートは、この互換処理ではデコードしません。同じ形式の完全な Win32 レポートだけを含むクリップボードテキストは区別できず、同様にデコードされます。
+
+## Windows で未サポート
+
+| 機能 | 状況 |
+| --- | --- |
+| ダイレクトターミナルアタッチ (`herdr terminal attach`) | 未サポート |
+| ライブサーバーハンドオフ | 未サポート |
+| Unix ファイルディスクリプタのハンドオフ | 未サポート |
+| Unix フォアグラウンドプロセスグループ | 未サポート |
+| ローカルのネイティブペインでの Herdr クリップボード画像ブリッジ | 未サポート |
+| 署名済みバイナリ / SmartScreen 回避 | 未サポート |
+
+Windows Terminal からは、Linux や macOS と同じリモートコマンドを使います:
+
+```powershell
+herdr --remote workbox
+```
+
+接続先ホストは Linux、macOS、Windows に対応します。Windows ホストでは `PATH` または現在有効な管理対象リリースから互換パッケージを再利用します。対話的なアタッチと保存済みマシンのセットアップは、必要に応じて完全なパッケージをインストール・更新する前に確認します。バックグラウンド再接続ではインストール済みパッケージだけを探し、インストールや更新の確認は行いません。Herdr はインストール済みの Windows OpenSSH クライアントと SSH 設定を使います。Windows OpenSSH では Herdr の Unix コントロールソケットによる接続再利用を使わないため、セットアップ中の繰り返しプロンプトを避けるには Windows の `ssh-agent` による鍵認証を推奨します。
+
+Windows のアップデートは Windows インストーラー経由で行われ、有効なバージョン付きリリースパスを更新します。新しいターミナルまたは再接続した SSH セッションはそのパスを受け取るため、そこで Herdr を起動すると更新済みクライアントを使えます。互換性のある実行中サーバーはペインを動かしたままにします。新しいリリースのサーバー側変更が必要になったときだけ、後からサーバーを再起動してください。ライブハンドオフは Unix 専用です。
+
+## Windows の問題を報告する
+
+以下を含めてください:
+
+- Herdr のバージョン。
+- Windows のバージョン。
+- ターミナルアプリ。
+- シェル (PowerShell、cmd など)。
+- 名前付き `HERDR_SESSION` を使っていたかどうか。
+- 関連する Herdr のログ。
+- 正確な再現手順。
@@ -0,0 +1,140 @@
+---
+title: Keyboard
+description: What the prefix is, which bindings to learn first, and how to go prefix-free.
+---
+
+:::tip[Coming from tmux or zellij?]
+You already know this model. Jump to the [keybinding reference](/docs/configuration/#keybindings) for the full default keymap and config syntax.
+:::
+
+Herdr is mouse-native. You can click panes, tabs, workspaces, and agents, drag split borders, and use right-click menus without learning a single keybinding. Keyboard control is optional.
+
+## What the prefix is
+
+A terminal multiplexer sits between your terminal and the programs running inside it. Those programs already use most key combinations: `ctrl+c` interrupts, `ctrl+r` searches history, editors claim nearly everything else. If Herdr grabbed common keys directly, it would break the programs inside it.
+
+The prefix solves this. Press the prefix key, default `ctrl+b`, and the next keypress goes to Herdr instead of your terminal. `prefix+c` means: press `ctrl+b`, release, then press `c`. Herdr reserves one key instead of dozens.
+
+Press `prefix+?` at any time to see every active binding. Press `/` in the keybind help to filter actions and shortcuts; use Backspace to edit the filter or `ctrl+u` to clear it.
+
+## Learn these five first
+
+| Action | Key |
+| --- | --- |
+| New tab | `prefix+c` |
+| Split right / down | `prefix+v` / `prefix+minus` |
+| Move between panes | `prefix+h/j/k/l` |
+| Workspace navigation | `prefix+w` |
+| Detach, leave everything running | `prefix+q` |
+
+These cover most daily movement. Everything else can stay on the mouse.
+
+## The rest, by task
+
+Panes:
+
+| Action | Key |
+| --- | --- |
+| Zoom the focused pane | `prefix+z` |
+| Close pane | `prefix+x` |
+| Swap panes | `prefix+shift+h/j/k/l` |
+| Resize mode | `prefix+r` |
+| Copy mode | `prefix+[` |
+
+Tabs:
+
+| Action | Key |
+| --- | --- |
+| Next / previous tab | `prefix+n` / `prefix+p` |
+| Jump to tab 1–9 | `prefix+1..9` |
+| Rename tab | `prefix+shift+t` |
+| Close tab | `prefix+shift+x` |
+
+Workspaces and session:
+
+| Action | Key |
+| --- | --- |
+| New workspace | `prefix+shift+n` |
+| Rename workspace | `prefix+shift+w` |
+| Close workspace | `prefix+shift+d` |
+| Goto picker | `prefix+g` |
+| Toggle sidebar | `prefix+b` |
+
+The full keymap and the binding syntax live in the [keybinding reference](/docs/configuration/#keybindings).
+
+The Goto picker (`prefix+g`) lists each agent or terminal on its own row, grouped by workspace. Split tabs never hide their panes behind another row. Click a row or press Enter to jump directly to it. Press `/` to search names, agent kinds, tabs, workspaces, branches, or paths; use Up/Down or `j/k` to move between rows when not typing a search. Left/Right jumps to the first agent or terminal in the previous/next workspace section, without wrapping. While editing a search, Left/Right moves the text cursor instead. Outside search, `b/w/i/d` filter blocked, working, idle, or done agents, and `a` shows all terminals again. The selected destination's location and path appear below the list. When the list overflows, use the mouse wheel, click the scrollbar track, or drag its thumb to scroll without opening a destination.
+
+Press Esc or Ctrl+[ to leave workspace navigation. In the Go To picker, `/` also opens search on layouts that require Shift to type it.
+
+Pane input follows the keyboard modes requested by the app. Plain shells receive Ctrl+Shift+letter as its control byte; Super, Hyper, and Meta chords are dropped when the pane cannot represent them. Apps using Kitty keyboard input receive the modifiers and key events they request. Without report-all mode, modified Enter, Tab, and Backspace do not receive release reports. Keypad keys and modifier-only presses are not forwarded.
+
+On non-Latin layouts, Ctrl-only shortcuts such as Ctrl+W can use the physical base key reported by a Kitty-capable host. Latin layout characters, Ctrl+Shift chords, and AltGr keep their layout meaning. Terminals that do not report physical keys cannot provide the same layout-independent shortcuts.
+
+## Editing text fields
+
+Herdr's naming dialogs, worktree branch fields, filters, and copy-mode search support editing at the cursor. These shortcuts apply to Herdr-owned fields, not to the shell or agent inside a pane.
+
+| Action | Keys |
+| --- | --- |
+| Move one character | Left / Right, Ctrl+B / Ctrl+F |
+| Move to the beginning / end | Home / End, Ctrl+A / Ctrl+E |
+| Move one word | Alt+B / Alt+F |
+| Delete the previous character | Backspace, Ctrl+H |
+| Delete the next character | Delete, Ctrl+D |
+| Cut to the beginning / end | Ctrl+U / Ctrl+K |
+| Cut the previous word | Ctrl+W, Alt+Backspace, Ctrl+Backspace |
+| Cut the next word | Alt+D |
+| Insert the last cut text | Ctrl+Y |
+
+Typing and paste insert at the cursor. Movement and deletion respect Unicode grapheme boundaries, and long values scroll horizontally. Cut text stays within the current field; it does not use the system clipboard. Alt shortcuts require the terminal to report Alt/Meta. Enter and Esc retain the dialog's confirm and cancel behavior.
+
+## Copy mode
+
+Press `prefix+[` to enter copy mode for the focused pane. Use `h/j/k/l`, tmux-style `w/b/e` and big-word `W/B/E`, `{`/`}`, `PageUp`/`PageDown`, `ctrl+b`/`ctrl+f`, and `ctrl+u`/`ctrl+d` to move. Press `/` or `?` for forward or backward literal search, then `n` or `N` to repeat in the same or opposite direction. Search is case-insensitive unless the query contains an uppercase letter. Use `v` or Space to start a selection, `y` or Enter to copy it, and `q` or Esc to leave without copying. Esc clears an active selection or search before exiting. Copy mode does not pause the pane process: output remains live, follows at the bottom, and stays pinned when you navigate into history. The configured prefix keeps its normal meaning in copy mode; with the default prefix, `ctrl+b` enters prefix mode instead of paging up, so use a different prefix if you want `ctrl+b` for copy-mode page-up. Mouse drag-select copies without entering copy mode at all.
+
+Mouse drag selections and selections started with `v`, Space, or `V` remain active during output and redraws, including when part of the selected range is outside the viewport. Copy reads the current text in that range, not a frozen snapshot. Resizing the pane or switching between its normal and alternate screens still clears the selection. Search results and double-click word selections retain their content-change checks.
+
+## Change anything
+
+Every binding is configurable, including the prefix itself:
+
+```toml
+[keys]
+prefix = "ctrl+a"
+```
+
+## Going prefix-free
+
+You can bind Herdr actions to direct chords that need no prefix at all. The hard part is knowing which chords are safe, because terminals, shells, and desktop environments already own most of the keyboard.
+
+Any chord works as a binding: `ctrl+j`, `alt+k`, whatever fits your hands. But a chord has to survive three layers before Herdr sees it: your operating system, your outer terminal (Ghostty, iTerm2, and others ship their own defaults), and the programs running inside the pane. `ctrl+j` reaches Herdr fine, but shells and editors treat it as enter. `alt+k` is free on Linux, but macOS composes it into a special character in most terminals. If you pick chords from these families, double-check them against your own terminal and OS shortcuts.
+
+We mapped the default keybindings of Ghostty, iTerm2, Terminal.app, kitty, WezTerm, Alacritty, Warp, Windows Terminal, GNOME Terminal, and Konsole, plus the global shortcuts of GNOME and KDE. One modifier family is almost untouched everywhere: `ctrl+alt`. Terminals leave it free, it is not affected by the macOS option-key composing behavior that blocks plain `alt` chords, and it transmits even in terminals without a modern keyboard protocol. It is a safe default, but the choice is yours.
+
+This setup keeps the prefix bindings working and adds direct chords on top:
+
+```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"]
+```
+
+A few `ctrl+alt` chords are taken elsewhere. Avoid these:
+
+| Chord | Owned by |
+| --- | --- |
+| `ctrl+alt+arrows` | GNOME workspace switching, Ghostty and Konsole defaults |
+| `ctrl+alt+t` | "Launch terminal" on Ubuntu and Fedora |
+| `ctrl+alt+l` / `ctrl+alt+a` | KDE lock screen / attention window |
+| `ctrl+alt+s` / `ctrl+alt+u` | Konsole |
+| `ctrl+alt+f1..f12` | Linux virtual console switching |
+
+If a direct chord does nothing, your terminal or desktop environment consumed it before Herdr could see it. Rebind either side: free the chord in the terminal's settings, or pick another chord in Herdr.
@@ -0,0 +1,54 @@
+---
+title: Marketplace
+description: Discover community Herdr plugins on GitHub, and get your own plugin listed.
+---
+
+The Herdr plugin marketplace indexes community plugins. Browse it at
+[herdr.dev/plugins](/plugins/). The index covers public GitHub repositories; it
+is not a reviewed catalog.
+
+## Browse plugins
+
+The [marketplace](/plugins/) lists public repositories tagged with the GitHub
+topic `herdr-plugin` when their default branch contains at least one
+`herdr-plugin.toml` whose required metadata can be parsed. Search by repository
+or plugin metadata, and sort repository cards by popularity, recent activity,
+or newest. Each card links to its source repository and lists every discovered
+plugin inside it.
+
+Discovery is automatic and unreviewed. A listing means a repository tagged
+itself, not that Herdr vetted it, so the
+[trust guidance](/docs/plugins/#trust-and-security) applies before you install
+anything.
+
+## Install a plugin
+
+The marketplace helps you discover plugins. Install any plugin straight from
+GitHub:
+
+```bash
+herdr plugin install owner/repo[/subdir...]
+```
+
+The command works with a public GitHub repository that has a
+`herdr-plugin.toml` manifest at its root or in a subdirectory. See
+[Plugins](/docs/plugins/) for the manifest and authoring reference.
+
+## Get your plugin listed
+
+Add the GitHub topic `herdr-plugin` to a public repository and put one or more
+`herdr-plugin.toml` manifests with parseable required metadata on its default
+branch. Manifests may be at the root or in subdirectories. The marketplace uses
+one card per repository and lists each valid manifest as a separately
+installable plugin. The index refreshes automatically every 30 minutes and
+rescans repositories when their default-branch head changes.
+
+## What a listing shows
+
+Each card shows GitHub repository metadata: the repository name and owner, its
+description, star count, primary language, and the time it was last pushed. Its
+plugin rows show each manifest's `name` and `version` and link to the exact
+source directory. The index records the manifest path, `id`, `name`, `version`,
+`platforms`, and `min_herdr_version` together with the exact default-branch
+commit. Forks, archived repositories, repositories without a valid plugin
+manifest, and malformed manifest metadata are excluded.
@@ -0,0 +1,164 @@
+---
+title: Persistence and remote access
+description: Detach from Herdr, reattach later, use named sessions, and connect over SSH.
+---
+
+Herdr keeps panes running in a background server. Your terminal client can detach and reconnect later.
+
+For the local, SSH, and `herdr --remote` workflows, see [How to work with Herdr](/docs/how-to-work/).
+
+## Detach and reattach
+
+Detach the client with `ctrl+b q`; panes and agents keep running. Reattach by running `herdr` again. Stop the session and its panes with `herdr server stop`.
+
+When Herdr starts again after a full server stop, it restores the saved session shape. For what survives detach, server restart, screen history replay, native agent session restore, and live handoff, see [Session state and restore](/docs/session-state/).
+
+On Linux and macOS, the server ignores `SIGHUP`, so a hangup from its launching shell does not stop the panes. To stop it deliberately, use `herdr server stop` or `SIGTERM`; scripts that previously used `SIGHUP` must change. Shutdown logs record the reason.
+
+## Named sessions
+
+Use named sessions when you want independent Herdr servers.
+
+```bash
+herdr session list
+herdr session attach work
+herdr session attach side-project
+herdr session stop work
+herdr session delete side-project
+```
+
+A named session has its own panes, tabs, workspaces, sockets, and runtime state. It still shares the same global config file.
+
+When deleting a session, use the exact name shown by `herdr session list`, including letter case. On case-insensitive filesystems, `herdr session delete foo` refuses to delete a session named `Foo`.
+
+Use `--json` for scripts:
+
+```bash
+herdr session list --json
+herdr session stop work --json
+herdr session delete side-project --json
+```
+
+## Saved SSH machines
+
+To keep Local and several SSH machines in one Herdr window, see [Connecting machines](/docs/connecting-machines/). That guide covers setup, switching, reconnects, settings, and remote automation. Removing a saved machine only disconnects the client; it does not stop that machine's sessions.
+
+## Remote attach over SSH
+
+[How to work with Herdr](/docs/how-to-work/) compares the connection paths. SSH to the server and run `herdr` there for the tmux-style path, use [saved SSH machines](/docs/connecting-machines/) for multi-machine work, or attach through SSH from your local machine:
+
+```bash
+herdr --remote workbox
+herdr --remote ssh://you@server:2222
+```
+
+Sidebar width, section split, collapsed groups, and agent sorting are saved locally for each remote target and session. Reattaching to the same target and session restores these preferences. Different SSH aliases or sessions have separate preferences.
+
+In this mode, the remote server owns the running panes and sends their terminal content and session state over SSH. Your local Herdr draws the UI, including its sidebar, menus, and theme. Because the client runs locally, Herdr can bridge local desktop features such as image clipboard paste into the remote session by copying the image to a remote temp file and pasting that path.
+
+By default, `herdr --remote` uses your local Herdr keybindings for that attach. This keeps local muscle memory even when the remote server has different config. After editing local keybindings, use the UI's `reload config` action to apply them without detaching. Use `--remote-keybindings server` when you want the remote server config instead. Local custom command keybindings are not sent, because those commands would run on the remote host.
+
+For repeat targets, use your SSH config:
+
+```text
+Host workbox
+  HostName server.example.com
+  User you
+  Port 2222
+```
+
+Then attach with:
+
+```bash
+herdr --remote workbox
+```
+
+Remote attach and saved SSH machines support Linux, macOS, and Windows local clients connecting to Linux or macOS hosts on x86_64 and aarch64, or Windows hosts on x86_64. Windows ARM64 hosts are supported on a best-effort basis using the x64 build under Windows emulation; bugs and issues are expected. Explicit remote attach and saved-machine setup display an emulation note when the host reports ARM64. Local and remote versions do not need to match once both support the stable endpoint generation. On Linux and macOS hosts, Herdr prefers a compatible `herdr` already on the remote `PATH`, then checks common direct, Homebrew, mise, and Nix profile install paths. On Windows hosts, Herdr checks `PATH` and the active managed release. If no compatible binary exists, interactive runs prompt to install or update one; non-interactive runs fail instead of modifying the host. Linux and macOS installs use `~/.local/bin/herdr`; Windows installs use the complete Windows package and its app-local ConPTY runtime. If `~/.local/bin` is not on the remote `PATH`, Herdr warns after install.
+
+By default, `herdr --remote` runs remote setup and the bridge through a temporary SSH config that includes your SSH config first, then adds fallback keepalive settings. Existing user keepalive settings win. Linux and macOS clients also use a private per-attach control socket for connection reuse; Windows OpenSSH does not. Set `[remote].manage_ssh_config = false` to use plain `ssh` without Herdr's generated config or control socket.
+
+Remote attach uses your normal OpenSSH authentication. If the target uses a passphrase-protected key in a non-interactive shell, script, CI job, or mobile terminal that cannot show the passphrase prompt, load the key into ssh-agent first:
+
+```bash
+ssh-add
+herdr --remote workbox
+```
+
+For any remote authentication failure, verify plain SSH access first with `ssh workbox`, then run `herdr --remote workbox` again.
+
+A version difference alone does not replace or restart a running remote server. Remote attach asks before stopping a server that lacks required compatibility or detached-daemon support. For saved machines, this also includes the surface and health-check capabilities described in [Connecting machines](/docs/connecting-machines/#updates-and-saved-data). The default answer is No; stopping the server ends its pane processes. To opt into experimental live handoff when that one-time upgrade is needed, pass `--handoff`:
+
+```bash
+herdr --remote workbox --handoff
+```
+
+If you SSH into the server first and run `herdr` there, Herdr runs entirely on the server and cannot access your local desktop clipboard beyond normal terminal text paste.
+
+For Linux and macOS hosts, Herdr can copy the current local binary when the platforms match. For Homebrew, mise, and Nix installs, when the platforms differ, or for Windows hosts, it downloads the matching release asset for the current client version from `https://herdr.dev/latest.json`.
+
+For local builds or custom packages, set `HERDR_REMOTE_BINARY` to a local file path before running remote attach. Use a bare Herdr executable for Linux or macOS targets and a complete `herdr-windows-x86_64.zip` package for Windows targets.
+
+```bash
+HERDR_REMOTE_BINARY=target/release/herdr herdr --remote workbox
+```
+
+## Remote named sessions
+
+Use `--session` with `--remote` to attach to a named session on the remote host:
+
+```bash
+herdr --remote workbox --session agents
+```
+
+## Direct terminal attach
+
+Full Herdr attach opens the whole workspace UI. Direct attach opens one server-owned terminal in your current terminal.
+
+Direct terminal attach is available on Linux and macOS, not native Windows.
+
+Attach by agent target:
+
+```bash
+herdr agent attach reviewer
+```
+
+Attach by terminal ID:
+
+```bash
+herdr terminal attach term_abc123
+```
+
+Direct attach streams the current rendered terminal state, then live ANSI frames. Input goes straight to that terminal.
+
+Detach with `ctrl+b q`. Send a literal `ctrl+b` with `ctrl+b ctrl+b`.
+
+Only one writable direct attach client owns input and resize for a terminal. Use `--takeover` to replace an existing owner:
+
+```bash
+herdr terminal attach term_abc123 --takeover
+```
+
+For third-party bridges that only need rendered terminal bytes, use a read-only
+terminal session observer:
+
+```bash
+herdr terminal session observe w1:p1 --cols 120 --rows 40
+```
+
+It prints newline-delimited JSON `terminal.frame` records with base64 ANSI
+bytes, then a `terminal.closed` record when the server closes the stream.
+Multiple observers can watch the same terminal without taking input, resize,
+scroll, or takeover ownership.
+
+For an interactive bridge, use a writable terminal session controller:
+
+```bash
+herdr terminal session control w1:p1 --takeover --cols 120 --rows 40
+```
+
+Control mode prints the same newline-delimited frame records and reads
+newline-delimited JSON commands on stdin. `terminal.input` sends text or
+base64 bytes, `terminal.resize` changes the controller viewport,
+`terminal.scroll` scrolls the attached viewport, `terminal.mouse` sends a mouse
+event at a cell to applications that enabled mouse reporting, and
+`terminal.release` closes the controller. Only one controller owns input and resize at a time.
@@ -0,0 +1,390 @@
+---
+title: Plugins
+description: Author local Herdr plugins with manifest actions, event hooks, and panes.
+---
+
+Herdr plugins are shareable, executable workflow packages. A plugin can be a
+Bash script, JavaScript app, Lua script, Rust binary, or any other argv command
+your machine can run. Herdr owns the host surface: installation, manifest
+validation, keybindings, terminal panes, events, invocation context, and socket
+access. The plugin owns its implementation language, dependencies, files, and
+durable state.
+
+Plugins exist so Herdr can stay lean. The core stays focused on terminal
+workspaces, panes, agents, and a stable CLI/socket API. Plugins turn that
+existing extension surface into reusable workflows that people can build,
+install, and share without adding every workflow to Herdr itself.
+
+A plugin is a directory with a `herdr-plugin.toml` manifest and commands Herdr
+can launch. Herdr validates the manifest, injects runtime context, starts the
+declared commands, and records logs. The commands call back into Herdr through
+the CLI or socket when they need to do more work.
+
+There is no separate plugin SDK or restricted command set. The entire Herdr CLI
+is the plugin API. Every command in the
+[CLI reference](/docs/cli-reference/) is available to a plugin, and a plugin can
+run anything you can run yourself as `herdr ...`. Most plugins should call Herdr
+through `HERDR_BIN_PATH`, which points at the running Herdr binary. That keeps
+plugins portable across Unix sockets and Windows named pipes. Use the
+[socket API](/docs/socket-api/) when you want to send raw JSON requests yourself.
+
+Runtime action registration and native non-terminal plugin UI are not part of
+plugin v1. Actions, event hooks, panes, and link handlers are all declared in
+the manifest.
+
+## Trust and security
+
+A plugin is ordinary code that runs on your machine. Its build and runtime
+commands run as your user, inherit your environment, and can call the full Herdr
+CLI. Treat a plugin like any extension you add to an editor, shell, or coding
+agent.
+
+Install or link plugins only from authors and repositories you trust. Before
+installing or linking one, skim the `herdr-plugin.toml` manifest and the scripts
+or binaries it runs. `herdr plugin install` shows a preview of the source and
+the commands it will run in interactive terminals, so you can review before
+confirming. Use `--yes` for
+sources you already trust, and pin `--ref` when you want a specific revision.
+
+Herdr validates the manifest and keeps each plugin's config and state in its own
+directory, but it does not review or sandbox plugin code. Third-party plugins
+come from their authors, not Herdr; you are responsible for deciding whether to
+run them.
+
+## Manifest
+
+The manifest is the contract between Herdr and the plugin. It declares package
+metadata, supported platforms, optional build commands, and the entrypoints
+Herdr can run.
+
+```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"]
+
+[[startup]]
+command = ["node", "dist/restore.js"]
+
+[[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"
+```
+
+Top-level `id`, `name`, `version`, and `min_herdr_version` are required.
+Set `min_herdr_version` to the oldest Herdr version that supports the plugin
+APIs, event names, and manifest fields your plugin uses. Herdr refuses to link
+or install a plugin when its minimum version is newer than the current binary.
+`description` is optional. Plugin ids may use ASCII letters, digits, dot,
+colon, underscore, and hyphen.
+
+Action ids, pane ids, and link handler ids are local ids inside the plugin.
+They may use ASCII letters, digits, colon, underscore, and hyphen, but not
+dots. Each id type must be unique inside a plugin. Herdr qualifies action ids
+as `plugin.id.action` when it needs a globally unique name.
+
+Use `platforms = ["linux", "macos", "windows"]` to declare where the plugin
+can run. Build commands, startup hooks, actions, event hooks, panes, and link
+handlers can also declare their own `platforms`; item-level platforms override
+the top-level list. Local plugins without top-level `platforms` link with a
+warning.
+
+`command` values are argv arrays. Herdr does not run them through a shell, so
+there is no shell expansion unless your command starts a shell itself. Put
+language-specific behavior in your script or binary.
+
+## First plugin
+
+Start with a directory that contains `herdr-plugin.toml` and one executable
+script or program:
+
+```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"]
+```
+
+Inside the command, call back into Herdr with `HERDR_BIN_PATH`:
+
+```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);
+```
+
+This example uses Node, but nothing about plugins requires Node. The manifest
+could launch Bash, PowerShell, Python, Rust, Go, Lua, Bun, or any other command
+available on the user's machine.
+
+## Install and link
+
+Install an example plugin:
+
+```bash
+herdr plugin install ogulcancelik/herdr-plugin-examples/agent-telegram-notify
+herdr plugin update
+herdr plugin config-dir examples.agent-telegram-notify
+herdr plugin list
+herdr plugin action list --plugin examples.agent-telegram-notify
+```
+
+When you are authoring a local plugin, link the working directory instead:
+
+```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` accepts GitHub shorthand only, such as
+`owner/repo/subdir`. It clones with `git`, shows a preview in interactive
+terminals, builds in a new Herdr-managed installation directory, and registers
+it. Use `--yes` for noninteractive installs. Updates and reinstalls leave the
+previous installation in place: running commands and panes keep their original
+files, while new invocations use the new installation without a config reload.
+Existing processes are not restarted, and startup hooks run at the next server
+startup as usual.
+`plugin update` refreshes every GitHub-managed plugin when called without a
+target, or only the listed plugin ids or GitHub sources. It refetches the ref
+recorded during install, skips unchanged commits, and ignores locally linked
+plugins during bulk updates. Use `--yes` for noninteractive updates.
+Installed and linked plugins, including their enabled state, are global to the
+current user and available in every Herdr session. Both `plugin install` and
+`plugin link` can register plugins while no Herdr server is running. Plugins
+installed only in a named session on Herdr 0.7.3 must be installed or linked
+again. Existing plugin config and state remain in place.
+Installing over a locally linked plugin is refused; unlink or uninstall the
+local plugin first. `plugin install` and `plugin link` create the plugin's
+config and state directories, and `plugin config-dir <id>` prints the config
+directory for setup docs and shell scripts.
+
+`plugin uninstall <id-or-source>` unregisters the plugin and accepts either the
+plugin id or the same `owner/repo[/subdir...]` shorthand used by install.
+Installation files are retained after updates, reinstalls, and uninstall so
+running plugins can finish. A later successful installation/update or server
+startup automatically removes obsolete managed installations once the servers
+using them have exited. Reloading config does not release old installations.
+Stop plugin work before shutting down its server: processes surviving server
+exit are not protected from cleanup. Plugins must stop detached background
+processes before their parent command or pane exits. Legacy installations
+without cleanup tracking are retained. Config and state are preserved.
+`plugin unlink <id>` only unregisters a plugin and leaves files alone, which is
+useful for local development.
+
+The example cookbook repo is `ogulcancelik/herdr-plugin-examples`. It contains
+separate example plugins in subdirectories, including `agent-telegram-notify`,
+`github-link-preview`, and `dev-layout-bootstrap`. Use them as examples to copy;
+Herdr does not maintain them as official plugins.
+
+## Build commands
+
+Build commands run during GitHub `plugin install` after confirmation and before
+Herdr registers the plugin. If a build command fails, install aborts and the
+plugin is not registered. `plugin link` does not run build commands; local
+authors build their working tree themselves. Build commands may generate files,
+but changing `herdr-plugin.toml` after the install preview aborts install. Build
+failures show the plugin id, build index, working directory, command, exit
+status or spawn error, and capped stdout/stderr without interpreting tool output.
+
+Build commands are plain argv commands too, but they do not receive runtime
+plugin context or Herdr socket env. Plugin authors should document required
+system tools such as `cargo`, `npm`, `bun`, or `lua`; Herdr reports build
+failures but does not install missing toolchains.
+
+## Startup hooks
+
+`[[startup]]` commands run once for each enabled plugin after Herdr restores the
+session and its API socket is ready. They run again when a new server takes over
+during live handoff, but not when a client attaches, config reloads, or a plugin
+is linked or enabled. Herdr starts them asynchronously and records their
+completion in the normal plugin command log. A startup failure does not stop the
+server.
+
+Startup hooks are one-shot initialization commands rather than supervised
+daemons. A hook should restore plugin-owned state, call any required Herdr APIs,
+and exit. For example, a plugin can save a declarative Agent view under
+`HERDR_PLUGIN_STATE_DIR`, then read and reapply that view from its startup hook.
+
+Startup hooks receive the normal runtime plugin environment and
+`HERDR_PLUGIN_EVENT=startup`. The install preview lists every startup command so
+users can review code that will run automatically.
+
+## Commands and environment
+
+Runtime commands run with the plugin directory as their working directory. Herdr
+injects `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`, and any available
+`HERDR_WORKSPACE_ID`, `HERDR_TAB_ID`, and `HERDR_PANE_ID`. Action commands also
+receive `HERDR_PLUGIN_ACTION_ID`; startup and event hooks receive
+`HERDR_PLUGIN_EVENT` (`startup` for startup hooks), event hooks additionally
+receive `HERDR_PLUGIN_EVENT_JSON`, and pane commands receive
+`HERDR_PLUGIN_ENTRYPOINT_ID`.
+
+`HERDR_PLUGIN_ROOT` is the installed or linked plugin directory. Do not store
+user credentials or durable state there, because GitHub-installed plugin roots
+are managed source checkouts. Put user-editable config such as `.env` files
+under `HERDR_PLUGIN_CONFIG_DIR`, and put local runtime state under
+`HERDR_PLUGIN_STATE_DIR`. Herdr creates those directories and seeds
+`HERDR_PLUGIN_CONFIG_DIR` from the legacy plugin config locations when present,
+but it does not validate, sync, or delete their contents. The plugin owns the
+file format and lifecycle.
+
+`HERDR_PLUGIN_CONTEXT_JSON` can include workspace, tab, focused pane, worktree,
+agent, selected text, clicked URL, and link handler fields when they are
+available for that invocation. Shell plugins can read the individual env vars
+for common ids, or parse the context JSON for the full shape.
+
+Use `HERDR_BIN_PATH` when a plugin needs to call Herdr portably from Node,
+PowerShell, Bash, or another runtime. The raw socket transport behind
+`HERDR_SOCKET_PATH` is OS-specific: Unix clients connect to a Unix socket path,
+while Windows clients connect to a named pipe. CLI calls through
+`HERDR_BIN_PATH` avoid that transport difference. See the
+[CLI reference](/docs/cli-reference/) for available commands and
+[socket API](/docs/socket-api/) for raw request shapes.
+
+## Panes
+
+Manifest pane `placement` defaults to `overlay`, which opens a temporary zoomed
+overlay over the active pane and restores the previous focus and zoom when it
+closes. A `plugin.pane.open` request can override the manifest placement with
+`overlay`, `popup`, `split`, `tab`, or `zoomed`.
+
+`placement = "popup"` opens a session-modal terminal popup without changing the
+tiled layout. It accepts optional `width` and `height` fields in the manifest or
+open request; omit them for the default half-size popup, use numbers for outer
+terminal-cell dimensions, or use strings like `"80%"` for a percentage of the
+terminal area. It receives all terminal input, including Escape, and closes
+when the command exits or a `popup.close` request is sent. Dimensions smaller
+than the popup minimum are clamped.
+
+Declare the placement directly on a plugin pane entrypoint when the pane should
+always be transient:
+
+```toml
+[[panes]]
+id = "picker"
+title = "Picker"
+platforms = ["linux", "macos"]
+placement = "popup"
+width = "80%"
+height = 20
+command = ["sh", "picker.sh"]
+```
+
+Split, tab, zoomed, and overlay plugin panes are normal Herdr panes after they
+open. Plugins can call standard pane APIs such as `pane.move`, `pane.swap`,
+`pane.resize`, and `pane.zoom` through the socket or CLI; Herdr keeps plugin
+pane ownership attached to the underlying pane when it moves across tabs or
+workspaces. A popup is a singleton session resource rather than a Herdr pane:
+it has no pane ID, does not change plugin focus context, emits no pane lifecycle
+events, and does not participate in pane, layout, persistence, or agent APIs.
+Its process does not receive `HERDR_PANE_ID`; the underlying tiled pane remains
+available through `HERDR_PLUGIN_CONTEXT_JSON`.
+Opening a popup returns `ui_busy` while Settings, Copy mode, or another Herdr
+modal is active, and `plugin.pane.open` returns an `ok` result after launch.
+
+On Windows, build commands, action commands, and event commands resolve common
+`PATHEXT` shims such as `npm.cmd`, `bun.cmd`, and `pnpm.cmd` when the bare
+command is on `PATH`. Pane commands use Herdr's normal Windows pane launcher and
+must still be valid Windows argv commands.
+
+## Keybindings
+
+Bind a key to an installed plugin action:
+
+```toml
+[[keys.command]]
+key = "prefix+l"
+type = "plugin_action"
+command = "example.layout.apply"
+description = "apply layout"
+```
+
+## Link handlers
+
+Use `[[link_handlers]]` to route modified clicks on matching terminal URLs to a
+plugin action instead of opening the URL in the browser. The modified-click
+modifier is Control on every platform, including macOS, because captured
+terminal mouse reports do not expose Command/Super separately from a plain
+click. `pattern` is a Rust regular expression matched against the clicked URL,
+and `action` must
+name an action declared by the same plugin. Link handler actions receive
+`invocation_source = "link_click"`, `clicked_url`, and `link_handler_id` in
+`HERDR_PLUGIN_CONTEXT_JSON`; shell plugins can also read
+`HERDR_PLUGIN_CLICKED_URL` and `HERDR_PLUGIN_LINK_HANDLER_ID`. Handlers are
+checked in manifest order inside each plugin.
+
+Link clicks invoke plugins only while `ui.mouse_capture` is enabled. Matching handlers run first. A launch failure shows an error and stops. Without a matching handler, only HTTP(S) links open externally. When capture is disabled, the outer terminal handles explicit hyperlinks using its own shortcuts and warnings. See [mouse controls](/docs/quick-start/#use-the-mouse) for the Windows Terminal URL detection caveat.
+
+## Storage
+
+There is no Herdr-managed plugin storage API in v1. Plugins that need durable
+state should own their files or database.
+
+## Marketplace
+
+Community plugins are discoverable in the [marketplace](/plugins/), an automatic
+index of public GitHub repositories tagged with `herdr-plugin` that contain one
+or more `herdr-plugin.toml` files whose required metadata can be parsed. Plugins
+stay ordinary GitHub repositories: publish one, then share
+`herdr plugin install owner/repo[/subdir]`.
+
+To get plugins listed, add the GitHub topic `herdr-plugin` and place their
+manifests at the root or in subdirectories of the repository's default branch.
+One repository card can contain multiple separately installable plugins. The
+index refreshes every 30 minutes. See
+[Marketplace](/docs/marketplace/) for how discovery works.
@@ -0,0 +1,75 @@
+---
+title: Quick start
+description: Create your first Herdr workspace and run agents in persistent terminal panes.
+---
+
+If Herdr is not installed yet, see [Install](/docs/install/). Then start Herdr from any project directory:
+
+```bash
+herdr
+```
+
+Herdr launches or attaches to your default background session. You do not manage sockets. If you detach, agents keep running.
+
+## Create a workspace
+
+When a session has no workspaces, Herdr opens one automatically. A workspace is a project-level container for tabs, panes, and agents. Give each active project its own workspace to keep agent state readable in the sidebar.
+
+## Use the mouse
+
+Herdr is mouse-native, so start by clicking panes, tabs, workspaces, and agents to focus them. Drag split borders to resize. Right-click for context menus, including splitting panes and creating tabs. Drag-select text to copy it to your clipboard. Double-click a token to select it, or hold the second press and drag to extend the selection by whole words. Both gestures copy when you release the mouse. Copying does not require Ctrl+C.
+
+Ctrl-click opens pane links when your terminal sends the modified click to Herdr. This works for OSC 8 hyperlinks and `http://` or `https://` URLs, including wrapped links whose beginning or end is outside the visible area. Hold Ctrl and move the pointer over a link to underline its visible segments. Hover highlighting clears when you move away, the pane content changes, or Herdr receives a Ctrl-release event; some terminals only report modifier changes with mouse movement.
+
+With `ui.mouse_capture = true` (the default), Herdr handles Ctrl-clicks. Matching enabled plugins run first. A handler launch failure shows an error and stops. Unmatched `http://` and `https://` links open in the default browser on the machine running the Herdr client. Other links need a matching plugin. Explicit hyperlinks are not advertised to the outer terminal in this mode, so native bypass clicks on labeled links are unavailable, including Command-click on macOS.
+
+With `ui.mouse_capture = false`, explicit hyperlinks are passed to the outer terminal. Use its normal link shortcuts and warnings. These clicks do not invoke Herdr plugins. Disabling capture also disables Herdr's mouse controls, including clicking tabs and dragging split borders.
+
+Windows Terminal can still intercept URLs it detects in visible text. For reliable plugin priority on those URLs, set `"experimental.detectURLs": false` in Windows Terminal's `settings.json`. This setting applies to all Windows Terminal profiles. Herdr does not change it.
+
+If you configure `ui.right_click_passthrough_modifier`, that modifier plus right-click sends right-click, hold, and drag gestures to mouse-reporting pane apps. To make normal right-click go to one pane app, choose **Send right-clicks to pane** from that pane's menu or run `herdr pane input --current --right-click pane` inside it. Right-click the pane frame to reopen Herdr's menu.
+
+## Run an agent
+
+Start your coding agent in a pane:
+
+```bash
+claude
+```
+
+Or `codex`, `pi`, `opencode`, or any other [supported agent](/docs/agents/). Herdr detects it automatically. Across every workspace, the sidebar shows whether each agent is `working`, `blocked`, `done`, or `idle`, so you always know which project needs you.
+
+## Keyboard control
+
+Keyboard control is optional; the mouse covers everything. Press `ctrl+b` to enter prefix mode, then press an action key.
+
+Common actions:
+
+| Action | Key |
+| --- | --- |
+| Split right | `prefix+v` |
+| Split down | `prefix+minus` |
+| New tab | `prefix+c` |
+| Next / previous tab | `prefix+n` / `prefix+p` |
+| Workspace navigation | `prefix+w` |
+| New workspace | `prefix+shift+n` |
+| Detach client | `prefix+q` |
+
+If the prefix idea is new to you, [Keyboard](/docs/keyboard/) explains what it is, why multiplexers use one, and how to go prefix-free. Press `prefix+?` inside Herdr to see every active binding, and `prefix+[` to copy from the keyboard in copy mode.
+
+## Detach and come back
+
+Press `prefix+q` or simply close your terminal window. The Herdr server and every agent keep running. Run `herdr` again to reattach to the same session.
+
+To end the session and stop its panes:
+
+```bash
+herdr server stop
+```
+
+## Where next
+
+- [Concepts](/docs/concepts/) — the workspace, tab, pane, and agent model in two minutes.
+- [How to work with Herdr](/docs/how-to-work/) — local, SSH, phone, and `herdr --remote` workflows.
+- [Agents](/docs/agents/) — supported agents, detection, and integrations that improve state accuracy.
+- [Configuration](/docs/configuration/) — keybindings, themes, notifications, and everything else.
@@ -0,0 +1,136 @@
+---
+title: Session state and restore
+description: Understand what Herdr keeps live, restores after restart, replays from history, resumes through agent integrations, and hands off during updates.
+---
+
+Herdr uses several state paths for different situations.
+
+## What survives
+
+| Case | Processes keep running | Layout returns | Recent screen returns | Agent conversation resumes |
+| --- | --- | --- | --- | --- |
+| Detach and reattach | Yes | Yes | Yes, from the live terminal | Yes, because the process never stopped |
+| Server restart | No | Yes | Only with pane screen history | Only with native agent session restore |
+| Update without `--handoff` | Compatible servers keep running; restart-required servers may need stop/restart | Yes after restart | Only with pane screen history | Only with native agent session restore |
+| Update with `--handoff` | Best effort for supported running servers | Yes | Yes, from the live terminal if handoff succeeds | Yes, because the process keeps running if handoff succeeds |
+
+## Live persistence
+
+Normal detach keeps the Herdr server running. Panes, shells, agents, servers, tests, and command processes keep running inside that server.
+
+Detach the client with `ctrl+b q`. Reattach later:
+
+```bash
+herdr
+```
+
+This is the strongest persistence path because the original processes never stop.
+
+## Snapshot restore
+
+If the Herdr server stops and starts again, the original pane processes are gone. Herdr restores the saved session shape: workspaces, tabs, panes, cwd, layout, and focus.
+
+Snapshot restore does not preserve running shells, servers, tests, or arbitrary processes. Panes that cannot use a stronger restore path come back as new shells in their saved directories.
+
+If a saved directory is unavailable or the shell cannot start, the pane stays in the layout with an error instead of disappearing or moving to your home directory. Its saved directory and agent session reference remain intact. Fix the directory or shell configuration and restart the server to retry, or explicitly close the pane to remove it.
+
+When saving, Herdr prefers the live shell's directory where the operating system exposes it, and retains the last confirmed directory after the shell exits. Shell-reported directories remain the fallback on other platforms.
+
+If `session.json` cannot be read or parsed, or requires a newer Herdr version, Herdr logs why loading failed. Before saving or clearing the replacement session, it preserves the original bytes in `session-backups/` beside `session.json` and logs the recovery path as `persist.backup`. A file missing at startup is checked again before the first save or clear. These failed-load recovery copies are separate from normal snapshot history.
+
+Herdr retains the three most recent recovery copies, pruning older copies only after a new copy is safely written. If preservation fails, autosave and shutdown leave the original untouched and log the failure; preservation is retried on the next save request. Copies are never restored automatically. To recover one, stop the affected server, copy the recovery file over its `session.json`, then restart. Recovery copies do not include pane screen history.
+
+## Shutdown and snapshot recovery
+
+On Linux systems with systemd-logind, Herdr listens for the host shutdown warning and requests a short delay while it saves and stops. This happens before logind proceeds with shutdown. The operating system limits the delay; Herdr does not block shutdown indefinitely. This protection is unavailable without logind and does not cover forced shutdown, power loss, or processes killed before the warning arrives.
+
+Herdr also keeps up to 48 layout snapshots in `session-snapshots/` beside `session.json`, on all platforms. The first saved layout is copied immediately. Later saves or clears can add a snapshot of the previous saved layout, at most once every 15 minutes. Unchanged snapshots are not duplicated. The interval survives server restarts, so a burst of pane exits or restarts cannot rotate away all older layouts. Recent changes may not be in the recovery snapshots.
+
+Normal pane closures still update `session.json`. There are no recovery prompts and no automatic restoration of older snapshots. To recover a layout:
+
+1. Find the affected session directory with `herdr session list --json`.
+2. Stop that server (`herdr server stop` for the default session, or `herdr session stop <name>` for a named session).
+3. Keep a copy of its current `session.json`, then copy the chosen file from `session-snapshots/` over `session.json`. File modification times identify when snapshots were taken.
+4. Start the session again.
+
+Snapshots contain layout and agent session references, not running processes or pane screen history. Treat them as private session data. A snapshot-write failure is logged but does not prevent the primary session from saving.
+
+## Pane screen history replay
+
+Pane screen history restores recent terminal contents after a full server restart without restoring the old process.
+
+Pane screen history is off by default because pane output can include secrets, tokens, prompts, and command output. Enable it in the config file:
+
+```toml
+[experimental]
+pane_history = true
+```
+
+When enabled, Herdr stores saved pane history in `session-history.json` next to `session.json`. Treat the Herdr config/session directory like terminal history.
+
+History is replayed only when it matches the exact saved layout. History from a different layout, including after manual snapshot recovery, is ignored. Older history files without layout verification are also ignored; newly saved history can be replayed on the next restart.
+
+## Native agent session restore
+
+Some agents can resume their own conversation sessions. Herdr can use official integration-reported session references to restart supported agent panes after a Herdr server restart.
+
+Native agent session restore is enabled by default. Disable it with:
+
+```toml
+[session]
+resume_agents_on_restore = false
+```
+
+Herdr resumes panes that reported a native session reference through a current official Herdr integration, and panes whose agent reported its own resume command. See [Add Herdr support to your agent](/docs/add-herdr-support/).
+
+After a client attaches and provides terminal size and theme context, Herdr resumes eligible restored agent panes across workspaces and tabs without waiting for each pane to be focused.
+
+Native session restore requires these Herdr integration versions or newer:
+
+| Agent | Minimum Herdr integration version | Resume command |
+| --- | --- | --- |
+| Pi | `2` | `pi --session <path-or-id>` |
+| Antigravity CLI | `1` | `agy --conversation <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>` |
+| Grok CLI | `2` | `grok --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>` |
+| Qwen Code | `1` | `qwen --resume <id>` |
+| Letta Code | `1` | `letta --conversation <id>` or `letta --conversation default --agent <agent-id>` for `default:<agent-id>` |
+| OpenCode | `5` | `opencode --session <id>` |
+| Kilo Code CLI | `1` | `kilo --session <id>` |
+| Hermes Agent | `2` | `hermes --resume <id>` |
+| MastraCode | `1` | `mastracode --thread <id>` |
+
+Run `herdr integration status` to check installed integration versions. Reinstall outdated integrations with `herdr integration install <agent>`.
+
+Unsupported, missing, invalid, duplicated, or stale session references restore as normal shells in the saved pane directory.
+
+If native agent session restore applies to a pane, Herdr resumes the agent session instead of replaying saved pane history for that pane.
+
+## Live handoff
+
+Live handoff is for update and remote attach flows that need to replace a running Herdr server. It asks the old server to transfer live panes to the new server, so pane processes can keep running across the server replacement.
+
+Unlike snapshot restore, pane history replay, and native agent session restore, handoff tries to keep the current processes alive rather than reconstructing state after the old server stops.
+
+A successful handoff preserves long-lived server-owned session state: pane PTYs and processes, agent identity and durable metadata, and plugin/session state needed by the replacement server. It does not preserve transient coordination across the replacement boundary. In-flight CLI or API requests, waits, subscription streams, client sockets, and pane-to-pane messages may be interrupted; clients should reconnect and retry them.
+
+Updated Unix servers can send more than 64 panes in one handoff by transferring them in batches. The sending server must already contain this support: an older running server still enforces its 64-pane limit on the first upgrade. That limit may require a normal server restart, which ends pane processes. Batching does not change update installation order or remove other handoff compatibility requirements.
+
+Live handoff is experimental and opt-in:
+
+```bash
+herdr update --handoff
+herdr --remote workbox --handoff
+```
+
+Plain `herdr update` installs the new client and keeps endpoint-generation-1 servers running. Plain `herdr --remote workbox` also keeps a compatible remote server running across version differences. A stop is required only for the one-time upgrade from a pre-generation-1 server; use `--handoff` when you explicitly want to replace a supported running server without losing its pane processes.
+
+`herdr update --handoff` only applies to installs managed by Herdr's own updater. Homebrew, mise, and Nix installs are updated through their package managers, so `herdr update` is disabled there and cannot perform live handoff.
@@ -0,0 +1,958 @@
+---
+title: Socket API
+description: Control a running Herdr server from scripts, tools, and coding agents.
+---
+
+Herdr exposes a local socket API for scripts and agents that need to inspect or control a running session.
+
+Most automation should start with the CLI wrappers. Use the raw socket API only when you need direct request/response control or long-lived event subscriptions.
+
+## Choose an integration layer
+
+| Layer | Use it for |
+| --- | --- |
+| Agent skill | Teaching a coding agent how to use Herdr from inside a pane. |
+| CLI wrappers | Shell scripts, simple orchestration, and human debugging. |
+| Raw socket API | Custom tools, protocol clients, and event subscribers. |
+
+The layers share the same control surface.
+
+## Schema
+
+The installed CLI can print the socket protocol schema bundled with that Herdr
+binary:
+
+```bash
+herdr api schema
+herdr api schema --json
+herdr api schema --output herdr-api.schema.json
+```
+
+Plain `herdr api schema` prints a short summary. `--json` prints the full JSON
+Schema document for tools, and `--output PATH` writes that document to a file.
+The schema covers raw requests, success responses, error responses, emitted
+events, and subscription events.
+
+## What you can control
+
+The socket API can:
+
+- create, list, focus, rename, and close workspaces
+- create, list, focus, rename, and close tabs
+- list, inspect, split, swap, focus, resize, rename, read, close, and send input to panes
+- list, inspect, read, prompt, wait on, rename, focus, start, and attach agents through CLI helpers
+- report custom agent state from hooks and plugins
+- subscribe to events and wait for output or state changes
+- install and uninstall built-in integrations
+- stop the server and reload config
+
+## CLI examples
+
+Create a workspace:
+
+```bash
+herdr workspace create --cwd ~/project --label api
+```
+
+Create a tab:
+
+```bash
+herdr tab create --label logs
+```
+
+Split a pane and run a command:
+
+```bash
+herdr pane split w1:p1 --direction right
+herdr pane run w1:p2 "npm test"
+```
+
+Inspect and rearrange panes:
+
+```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
+```
+
+Wait for an agent:
+
+```bash
+herdr agent wait w1:p1 --until done
+```
+
+Read pane output:
+
+```bash
+herdr pane read w1:p2 --source recent --lines 50
+```
+
+## Raw methods
+
+Raw socket method names use dot notation:
+
+| Area | Methods |
+| --- | --- |
+| Server | `ping`, `server.stop`, `server.reload_config`, `server.agent_manifests`, `server.reload_agent_manifests` |
+| Notification | `notification.show` |
+| Client | `client.window_title.set`, `client.window_title.clear` |
+| Session | `session.snapshot` |
+| Workspace | `workspace.create`, `workspace.list`, `workspace.get`, `workspace.focus`, `workspace.rename`, `workspace.move`, `workspace.move_block`, `workspace.report_metadata`, `workspace.close` |
+| Worktree | `worktree.list`, `worktree.create`, `worktree.open`, `worktree.remove` |
+| Tab | `tab.create`, `tab.list`, `tab.get`, `tab.focus`, `tab.rename`, `tab.move`, `tab.close` |
+| Pane | `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` |
+| Popup | `popup.close` |
+| Layout | `layout.export`, `layout.apply`, `layout.set_split_ratio` |
+| Agent | `agent.list`, `agent.get`, `agent.read`, `agent.explain`, `agent.send_keys`, `agent.prompt`, `agent.wait`, `agent.rename`, `agent.focus`, `agent.start`, `agent.view.set`, `agent.view.clear` |
+| Events | `events.subscribe`, `events.wait` |
+| Integrations | `integration.install`, `integration.uninstall` |
+| Plugins | `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` |
+
+`agent.wait` is server-owned and event-driven. It pins the resolved pane occupant so a replacement cannot satisfy the wait. `agent.prompt` accepts an optional `wait` object with `until` and `timeout_ms`; this submits the prompt and starts the wait in one request, avoiding a race between separate calls. If the resolved agent is already `blocked`, `agent.prompt` returns `agent_blocked` without sending input or starting the wait.
+
+`workspace.move_block` atomically moves the ordered `workspace_ids` before `before_workspace_id`; omit the anchor to move the block to the end. The ids must be unique and the anchor cannot be part of the block. The response contains the authoritative ordered workspace list.
+
+`session.snapshot` returns a one-time bootstrap snapshot for clients that keep
+their own local runtime cache. The response includes version/protocol metadata,
+focused workspace/tab/pane ids, workspace records, tab records, pane records,
+tab layout snapshots, and agent records. It is not a subscription. For cache
+bootstrap and recovery, subscribe first, then reconcile through authoritative
+reads as described under Event subscriptions below. Events invalidate cached state; they
+cannot be unconditionally replayed over a snapshot. Call `session.snapshot`
+again after reconnecting or when the local cache may be stale. Attached worktree provenance is included on workspace
+records. Full repo worktree discovery remains `worktree.list`.
+
+From the CLI, `herdr api snapshot` prints the live `session.snapshot` response
+as JSON for clients and agents that want a simple bootstrap command.
+
+Pane control methods use public pane ids such as `w1:p1`. Methods whose
+schema makes `pane_id` optional use the server's active focused pane when it is
+omitted. `pane.move` always requires the source `pane_id`.
+
+`pane.send_keys` and `pane.send_input.keys` accept Herdr key-combo strings:
+plain printable keys, special keys like `enter` and `esc`, modifier chords
+like `ctrl+h`, `control+j`, `alt+x`, and `shift+tab`, function keys like
+`f1`, and named punctuation like `minus` and `plus`. They do not accept
+`prefix+` binding strings.
+
+On macOS, `pane.send_input` (used by `pane run`) and `agent.start` check the terminal's current canonical input limit before accepting a command into the input queue. An oversized encoded line, including Enter, is rejected in full; wait for the shell prompt and retry. Multiple short lines and raw-mode input remain supported. Successful responses still acknowledge queue admission, not command execution. This check covers the current submission only: it cannot inspect an earlier incomplete line or guarantee the terminal mode will remain unchanged while input is queued.
+
+```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_input","method":"pane.input.set","params":{"pane_id":"w1:p1","right_click":"pane"}}
+{"id":"req_split","method":"pane.split","params":{"direction":"right","ratio":0.333,"right_click":"pane","env":{"HERDR_ROLE":"tests"}}}
+{"id":"req_process","method":"pane.process_info","params":{"pane_id":"w1:p1"}}
+```
+
+`pane.current` returns a single `PaneInfo`. When `caller_pane_id` is present,
+Herdr returns that pane. When it is omitted, Herdr returns the active focused
+pane.
+
+`pane.input.set` sets `right_click` to `herdr` or `pane` for one pane. `herdr`
+is the default. `pane` forwards unmodified right-click hold and drag gestures
+when the application requests terminal mouse reporting; otherwise Herdr falls
+back to its pane menu. Right-clicking the pane frame always opens Herdr's menu.
+`pane.split` accepts the same optional `right_click` value for the newly created
+pane.
+
+`PaneInfo` includes `scroll` when terminal scroll metrics are available:
+
+```json
+{
+  "offset_from_bottom": 12,
+  "max_offset_from_bottom": 240,
+  "viewport_rows": 30
+}
+```
+
+Clients can treat `offset_from_bottom == 0` as at-bottom state.
+
+### Pane graphics
+
+Applications and plugins should emit the standard Kitty graphics protocol through
+their pane's terminal output. Herdr manages image placement, clipping, and
+visibility in compatible outer terminals.
+
+The external socket pane-overlay API has been removed: `pane.graphics.info`,
+`pane.graphics.set`, `pane.graphics.clear`, and `pane.graphics.stream` are no
+longer available. There is no replacement socket image API. Internal wire
+compatibility with older servers does not restore these public methods.
+
+`pane.layout` returns the tab layout snapshot with `workspace_id`, `tab_id`,
+`zoomed`, outer `area`, `focused_pane_id`, pane rects, and split rects/ratios.
+`pane.neighbor` and `pane.edges` include that same layout snapshot so clients
+can make the next decision without private layout state.
+
+`pane.process_info` returns the pane's shell pid, foreground process group id
+when available, and foreground processes with pid, name, argv/cmdline, and cwd
+when the platform exposes them.
+
+`layout.export` returns a portable tab layout tree. Omit `tab_id` and `pane_id`
+to export the active tab, pass `tab_id` to export that tab, or pass `pane_id` to
+export the tab containing that pane.
+
+```json
+{"id":"req_export","method":"layout.export","params":{"tab_id":"w1:t1"}}
+```
+
+The response includes `workspace_id`, `tab_id`, `zoomed`, `focused_pane_id`, and
+`root`. `root` is a BSP tree of `pane` and `split` nodes. Pane nodes can include
+`pane_id`, `label`, `cwd`, and argv `command`. Split nodes use
+`direction` (`right` or `down`), `ratio`, `first`, and `second`.
+
+`layout.apply` creates a fresh tab from a declarative tree. If `tab_id` is
+provided, Herdr creates the replacement tab first and then closes the old tab.
+This restores structure, labels, cwd, env, and optional argv commands; it does
+not preserve live PTYs, scrollback, or running processes.
+
+```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" }
+      }
+    }
+  }
+}
+```
+
+`layout.set_split_ratio` updates an existing split in a tab layout. The response
+is `type: "layout_split_ratio_set"` with the updated portable `layout`.
+
+```json
+{"id":"req_ratio","method":"layout.set_split_ratio","params":{"tab_id":"w1:t1","path":[],"ratio":0.6}}
+```
+
+Process-launching methods accept an `env` object. Herdr applies those key/value
+pairs to the newly launched process only. Herdr also injects `HERDR_SOCKET_PATH`,
+`HERDR_ENV=1`, `HERDR_WORKSPACE_ID`, `HERDR_TAB_ID`, and `HERDR_PANE_ID` into
+managed pane processes. Herdr-managed variables are authoritative when they
+conflict with caller-provided env.
+
+`pane.swap` supports directional and explicit forms:
+
+```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"}}
+```
+
+Swap is same-tab only. It preserves split shape, split ratios, pane ids, and
+running processes. The response is `type: "pane_swap"` with `changed`, optional
+`reason`, `source_pane_id`, optional `target_pane_id`, `focused_pane_id`, and
+`layout`. Reason values are `no_neighbor`, `same_pane`, `not_found`, and
+`cross_tab`. When a tab is zoomed, swap keeps zoom active and mutates the hidden
+full-tab layout.
+
+`pane.move` moves a running pane to a different tab, a new tab, or a new
+workspace:
+
+```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}}
+```
+
+Existing-tab moves require `split: "right" | "down"`. `target_pane_id` is
+optional and defaults to the target tab's focused pane. Same-tab layout changes
+remain `pane.swap`; moving to the source tab returns `changed: false` with
+`reason: "same_tab"`. Moves involving a zoomed source or target tab return
+`changed: false` with `reason: "zoomed_tab"`.
+
+The response is `type: "pane_move"` with `changed`, optional `reason`,
+`previous_pane_id`, `previous_workspace_id`, `previous_tab_id`, the moved
+`pane`, optional `source_layout`, `target_layout`, optional created workspace or
+tab records, optional closed workspace or tab ids, and `focused_pane_id`.
+Cross-workspace moves keep the internal pane and terminal alive but assign a new
+public pane id in the destination workspace. Subscribers can listen for
+`pane.moved`; Herdr does not emit fake pane close/create events for the moved
+terminal process.
+
+`pane.zoom` toggles, enables, or disables zoom for the target pane's tab:
+
+```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"}}
+```
+
+Omitting `pane_id` targets the server's active focused pane. The response is
+`type: "pane_zoom"` with `changed`, `zoom_changed`, `focus_changed`, optional
+`reason`, `pane_id`, `focused_pane_id`, `zoomed`, and `layout`. `changed` is
+true when either zoom state or focus changed. Reason values are `single_pane`,
+`already_zoomed`, and `already_unzoomed`.
+
+The CLI wrapper for `notification.show` is:
+
+```bash
+herdr notification show "build failed" --body "api workspace" --position top-left --sound request
+```
+
+Show a user notification through the configured toast delivery:
+
+```json
+{"id":"req_notify","method":"notification.show","params":{"title":"build failed","body":"api workspace","position":"top-left","sound":"request"}}
+```
+
+`title` is required and must contain visible text after control characters and repeated whitespace are removed. `body` is optional. Herdr collapses newlines, tabs, carriage returns, and repeated whitespace into spaces, then trims notification text to 80 characters for `title` and 240 characters for `body`. An empty sanitized `title` returns `invalid_params`. `position` is optional and applies only when `ui.toast.delivery = "herdr"`; desktop positions are relative to the full Herdr frame, and omitted positions use `ui.toast.herdr.position`. Terminal, system, and off delivery ignore `position`. `sound` is optional and can be `none`, `done`, or `request`; it defaults to `none` and plays only when the notification is shown.
+
+The response reports whether anything was shown:
+
+```json
+{"id":"req_notify","result":{"type":"notification_show","shown":true,"reason":"shown"}}
+```
+
+Possible reasons are `shown`, `disabled`, `rate_limited`, `no_foreground_client`, and `busy`. `disabled` means `ui.toast.delivery = "off"`. `busy` means an existing in-app toast was not replaced. Terminal and system delivery are best-effort through the current foreground attached Herdr client.
+
+Set or clear the foreground client's outer terminal window title:
+
+```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` hands the title back to `ui.window_title`. The response is
+`type: "client_window_title"` with `changed` and reason `set`, `cleared`, or
+`no_foreground_client`.
+
+Worktree methods manage Git checkouts as Herdr workspaces. `worktree.create` creates a checkout and returns the new `workspace`, `tab`, `root_pane`, and `worktree` records. If the requested branch already exists locally, it checks out that branch; otherwise it creates the branch from the requested base or `HEAD`. `worktree.open` opens an existing checkout or returns the already-open workspace. `worktree.remove` runs `git worktree remove` against a linked child workspace and never deletes the branch.
+
+Create a worktree from a source workspace:
+
+```json
+{"id":"req_1","method":"worktree.create","params":{"workspace_id":"w1","branch":"worktree/api","focus":false}}
+```
+
+Open an existing checkout:
+
+```json
+{"id":"req_2","method":"worktree.open","params":{"workspace_id":"w1","branch":"worktree/api","focus":true}}
+```
+
+Remove a linked checkout:
+
+```json
+{"id":"req_3","method":"worktree.remove","params":{"workspace_id":"2","force":false}}
+```
+
+Use at most one of `workspace_id` or `cwd` for `worktree.list`, `worktree.create`, and `worktree.open`; omit both to use the active workspace. Use exactly one of `path` or `branch` for `worktree.open`. Raw socket `cwd` and `path` values must be absolute; the CLI expands relative `--cwd` and `--path` values before sending requests. Workspace responses include optional `worktree` provenance when a workspace belongs to a Herdr worktree group. Worktree commands can emit `workspace.updated` when an existing workspace gains or changes worktree provenance.
+
+Worktree commands also emit lifecycle events. `worktree.create` emits `workspace.created`, `tab.created`, `pane.created`, and `worktree.created`. `worktree.open` emits `worktree.opened`, and it also emits workspace/tab/pane creation events when it opens a new Herdr workspace. `worktree.remove` emits `worktree.removed`; if the linked workspace is still open, it also emits `workspace.closed`.
+
+`workspace.close` rejects closing a primary workspace while linked-worktree workspaces are open unless its params include `"close_group": true`, returning `workspace_group_close_required` when explicit group intent is missing. An explicit group close emits one `workspace.closed` event for each workspace it closes.
+
+## Agent view queries
+
+`agent.view.set` installs one transient declarative projection for the built-in
+Agents view. The projection is reevaluated whenever agent facts or current UI
+context change. It controls the expanded and collapsed sidebar, mobile Agents
+list, mouse targets, indexed focus, and next/previous Agent navigation. It does
+not change `agent.list`, notifications, detection, or global attention counts.
+
+Show agents in the currently presented Space or agents needing attention
+elsewhere, then order by attention and most recent state transition:
+
+```json
+{
+  "id": "view_set",
+  "method": "agent.view.set",
+  "params": {
+    "source": "plugin:example.agent-views",
+    "label": "focus",
+    "filter": {
+      "op": "any",
+      "filters": [
+        {
+          "op": "eq",
+          "field": "workspace_id",
+          "value": {"context": "current_workspace_id"}
+        },
+        {
+          "op": "in",
+          "field": "status",
+          "values": ["blocked", "done"]
+        }
+      ]
+    },
+    "sort": [
+      {"field": "attention", "order": "desc"},
+      {"field": "state_change_seq", "order": "desc"}
+    ]
+  }
+}
+```
+
+Filter nodes use `op` values `all`, `any`, `not`, `eq`, `in`, or `exists`.
+Built-in filter fields are `status`, `workspace_id`, `tab_id`, `pane_id`,
+`agent`, `seen`, and `state_change_seq`. Use `{"token":"name"}` as a field to
+filter plugin-reported pane metadata. Values are strings, booleans, unsigned
+numbers, or a context object. Context values are `current_workspace_id` and
+`current_tab_id`, and may only be compared to the matching ID field. In a
+saved-machine client, the selected server's view applies to the combined agent
+list. Current workspace and tab context includes that selected machine, so an
+identical ID on another machine does not match; independent filter branches,
+such as `status` being `blocked`, still match agents on any connected machine.
+Effective status values are `idle`, `working`, `blocked`, `done`, and `unknown`;
+`done` means idle and not yet seen.
+
+Sort fields are `workspace_order`, `tab_order`, `pane_order`, `attention`,
+`status`, `agent`, `seen`, `state_change_seq`, or `{"token":"name"}`. Sorts are
+stable, evaluated in order, and accept `asc` or `desc`. Missing values stay
+after present values. When `sort` is omitted, the existing
+`ui.agent_panel_sort` policy remains active. A custom sort temporarily replaces
+that policy without rewriting config.
+
+`source` identifies the owner. Plugins use `plugin:<HERDR_PLUGIN_ID>`; Herdr
+rejects plugin-owned sets when that plugin is missing or disabled. Other callers
+may use their own non-`plugin:` source. A successful set atomically replaces the
+previous view. The view lasts until it is cleared, replaced, its owning plugin
+is disabled, unlinked, or uninstalled, or the server exits. Plugins that want
+durable behavior should save the query under `HERDR_PLUGIN_STATE_DIR` and
+reapply it from a `[[startup]]` hook.
+
+Clear unconditionally, or only when the named source still owns the view:
+
+```json
+{"id":"view_clear","method":"agent.view.clear","params":{}}
+{"id":"view_clear_owned","method":"agent.view.clear","params":{"source":"plugin:example.agent-views"}}
+```
+
+A source mismatch leaves the active view unchanged. Set and clear responses use
+`type: "agent_view"` and report `active`, `source`, and optional `label`.
+
+## Plugin APIs
+
+The plugin API is an early interface for executable workflow tools. A plugin is
+a package with a `herdr-plugin.toml` manifest. The manifest declares startup
+hooks, shareable actions, event hooks, terminal pane entrypoints, and link
+handlers. Startup hooks run once after restore when the API is ready.
+Actions and panes are manifest-only; runtime action registration and runtime
+argv pane creation are not part of v1.
+
+Installed and linked plugins persist across restarts. Herdr writes a
+`plugins.json` registry file alongside `session.json` on `plugin.link`,
+`plugin.unlink`, `plugin.enable`, and `plugin.disable`. The
+`herdr plugin install` and `herdr plugin link` CLIs also write the same registry
+when Herdr is not running, then startup loads it automatically. On startup,
+Herdr re-reads each manifest from its original path; if the file is missing or
+unparseable, the entry is kept with a `warnings` field so `plugin.list` surfaces
+it.
+
+Herdr validates event hook `on` values against known event names at link time.
+An unrecognised name does not block the link, but the returned plugin info
+includes a warning (e.g. `"unknown event 'worktree.craeted'"`). Check the
+`warnings` field in the `plugin.link` and `plugin.list` responses.
+
+Link a local plugin manifest:
+
+```json
+{"id":"req_plugin_link","method":"plugin.link","params":{"path":"/path/to/plugin","enabled":true}}
+```
+
+`plugin.link` also accepts optional `source` metadata. The CLI uses this when it installs from GitHub so `plugin.list` can show origin, requested ref, resolved commit, and managed checkout path:
+
+```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}}}
+```
+
+The path can be a plugin directory containing `herdr-plugin.toml` or a direct
+manifest path. The manifest shape is:
+
+```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` is required. The server refuses to link a plugin when the
+field is missing, invalid, or newer than the running Herdr binary.
+
+Declare `platforms` at the top level with the OS identifiers (`linux`, `macos`,
+`windows`) your plugin supports. Omitting `platforms` is allowed for local
+development. `plugin.link` succeeds, but the response includes a warning.
+Individual build commands, actions, event hooks, panes, and link handlers can
+declare their own `platforms` to override the plugin-level list; if omitted they
+inherit from the plugin. Invoking an action or opening a pane whose effective
+platforms do not include the current OS returns a `platform_unsupported` error.
+
+List, enable, disable, or unlink linked plugins:
+
+```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"}}
+```
+
+Actions are resolved from the linked manifest. `plugin.action.list` returns all actions across installed plugins; pass `plugin_id` to filter.
+
+```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` returns each action's effective `platforms` after applying
+plugin-level inheritance.
+
+Invoke an action by its qualified id or bare action id:
+
+```json
+{"id":"req_plugin_invoke","method":"plugin.action.invoke","params":{"action_id":"example.worktree-bootstrap.bootstrap","context":{"invocation_source":"keybinding"}}}
+```
+
+`plugin.action.invoke` resolves the manifest action, starts the manifest
+command, and returns the Herdr-built invocation context plus the started command
+log record. Missing context fields are filled from the active workspace, tab,
+focused pane, worktree provenance, and request id. Invoking an action from a
+disabled plugin returns a `plugin_disabled` error.
+
+Herdr injects `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`, and available
+`HERDR_WORKSPACE_ID`, `HERDR_TAB_ID`, and `HERDR_PANE_ID` values. Action
+commands also receive `HERDR_PLUGIN_ACTION_ID`; event hooks receive
+`HERDR_PLUGIN_EVENT` and `HERDR_PLUGIN_EVENT_JSON`; pane commands receive
+`HERDR_PLUGIN_ENTRYPOINT_ID`.
+
+List recent action and event command logs:
+
+```json
+{"id":"req_plugin_logs","method":"plugin.log.list","params":{"plugin_id":"example.worktree-bootstrap","limit":20}}
+```
+
+Event hooks run for enabled installed plugins when Herdr emits a matching event
+name such as `worktree.created`.
+
+There is no Herdr-managed plugin storage API in v1. `HERDR_PLUGIN_CONFIG_DIR`
+and `HERDR_PLUGIN_STATE_DIR` are path discovery only; plugins own their files,
+schemas, migrations, and cleanup.
+
+Open a managed terminal 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` requires an installed, enabled, platform-compatible plugin,
+then launches the requested manifest `[[panes]]` entrypoint as an argv-backed
+terminal pane. Manifest pane `placement` defaults to `overlay`; request
+`placement` overrides the manifest with `overlay`, `popup`, `split`, `tab`, or
+`zoomed`. Overlay and popup placements use the active tiled pane as launch
+context. Popup terminals are session-modal and do not change the tab layout;
+optional `width` and `height` fields set their outer size as terminal cells or
+percentages such as `"80%"`. Omitted dimensions default to half the terminal
+size, with too-small values clamped to the popup minimum. A popup has no pane
+ID, remains outside all `pane.*` and agent APIs, emits no pane lifecycle events,
+leaves plugin focus context on the underlying tiled pane, and does not export
+`HERDR_PANE_ID` to its process. Popup launch returns `ok`; `popup.close` closes
+the active popup and returns
+`popup_not_open` when none exists. Split and zoomed panes target an existing
+pane; tab panes can target a workspace. Split, tab, zoomed, and overlay panes
+behave like normal Herdr panes, and `plugin.pane.focus` and `plugin.pane.close`
+continue to operate on those panes.
+
+## Socket transport
+
+Herdr uses newline-delimited JSON over a local socket. On Unix, that socket is a
+Unix domain socket. On Windows, it is a named pipe.
+
+Send one request per line:
+
+```json
+{"id":"req_1","method":"ping","params":{}}
+```
+
+A successful response includes the same `id`:
+
+```json
+{"id":"req_1","result":{"type":"pong"}}
+```
+
+For request lines that reach JSON decoding, error responses also echo the request's
+`id`, including when the method or parameters are invalid. If the JSON is invalid
+or has no unambiguous top-level string `id`, the error response uses an empty `id`.
+Transport errors, such as invalid UTF-8, can close the connection without a response.
+
+Event subscriptions keep the connection open after the initial response.
+
+## Socket paths
+
+The default socket lives under your Herdr config directory.
+
+Named sessions have separate sockets:
+
+```text
+~/.config/herdr/herdr.sock
+~/.config/herdr/sessions/<name>/herdr.sock
+```
+
+Resolution order:
+
+1. explicit CLI `--session <name>`
+2. `HERDR_SOCKET_PATH`
+3. `HERDR_SESSION=<name>`
+4. default session socket
+
+Use `HERDR_SOCKET_PATH` only for low-level overrides.
+
+For plugins, prefer invoking `HERDR_BIN_PATH` and the CLI wrappers when you need
+portable Windows behavior. Raw socket clients are responsible for using the
+platform-native local socket form.
+
+## Agent state reporting
+
+Integrations report agent state with `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"
+  }
+}
+```
+
+`state` carries semantic agent state and affects waits, notifications, and
+rollups. Report display-only values separately through metadata.
+
+Session-only official integrations report native session references with `pane.report_agent_session`. State-reporting integrations can still include native session references in `pane.report_agent`. State-independent session reports do not affect waits, notifications, or rollups.
+
+```json
+{
+  "id": "req_2",
+  "method": "pane.report_agent_session",
+  "params": {
+    "pane_id": "w1:p1",
+    "source": "herdr:codex",
+    "agent": "codex",
+    "agent_session_id": "..."
+  }
+}
+```
+
+Both methods accept an optional `resume_argv` array with the command that resumes the reporter's current session after a Herdr server restart. Its first element must be a plain command name, not a path. It allows at most 64 elements and 8 KiB in total, and no element may contain an apostrophe or control character; invalid values fail with `invalid_resume_argv` and the report is not applied. A custom agent must hold the pane through `pane.report_agent` before it can attach a command; otherwise the request fails with `resume_not_accepted`. Herdr keeps the command only while the same `source` and `agent` hold the pane, and it takes precedence over Herdr's built-in resume command for that agent. Older Herdr versions ignore the field.
+
+```json
+{
+  "id": "req_3",
+  "method": "pane.report_agent_session",
+  "params": {
+    "pane_id": "w1:p1",
+    "source": "custom:my-agent",
+    "agent": "my-agent",
+    "agent_session_id": "...",
+    "resume_argv": ["my-agent", "--resume", "..."]
+  }
+}
+```
+
+`pane.get`, `pane.list`, `agent.get`, and `agent.list` expose a read-only `agent_session` object when Herdr has a stored native session reference:
+
+```json
+{
+  "agent_session": {
+    "source": "herdr:codex",
+    "agent": "codex",
+    "kind": "id",
+    "value": "..."
+  }
+}
+```
+
+If no native session reference is stored, the field is omitted.
+
+`pane.get`, `pane.list`, `agent.get`, and `agent.list` also expose `foreground_cwd` when Herdr can resolve the cwd of the process currently controlling the pane PTY. The existing `cwd` field remains the pane/workspace cwd used for labels, follow-cwd behavior, and restored session state.
+
+`PaneInfo` and `AgentInfo` expose optional `terminal_title` and `terminal_title_stripped` fields. `terminal_title` is the latest OSC 0/2 title after safety normalization. `terminal_title_stripped` removes one recognized leading activity or spinner glyph and following whitespace. These server-owned values are ephemeral across a cold restart and are independent of the metadata `title` and semantic agent state.
+
+Use `pane.report_metadata` when a user hook wants to customize presentation without taking over lifecycle state from a Herdr integration.
+
+```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",
+    "state_labels": {
+      "working": "refactoring auth",
+      "idle": "ready",
+      "done": "review ready"
+    },
+    "tokens": {
+      "summary": "refactor auth",
+      "model": "opus"
+    },
+    "ttl_ms": 3600000
+  }
+}
+```
+
+Metadata reports are display-only. Valid metadata can override the pane title, displayed agent name, visible state labels, and arbitrary named tokens. `working`, `blocked`, `idle`, waits, notifications, and rollups still come from semantic state. Native session restore comes from stored official session references. `agent` is an optional guard for presentation fields against the authoritative agent label; `applies_to_source` similarly guards presentation fields against the active lifecycle authority source. These guards do not apply to token patches: token reporters own clearing and TTL refresh. Use `display_agent` to change the visible name. `state_labels` keys must be `idle`, `working`, `blocked`, `done`, or `unknown`.
+
+Token maps are per-resource patches. A string sets a key, JSON `null` clears it, and omitted keys remain unchanged. The latest accepted update wins. Optional TTL applies independently to token keys updated by that report. Pane tokens are exposed by pane and agent get/list responses and can be rendered as `$name` in Agent sidebar rows. A report may mention at most 16 token keys, and a pane or workspace may retain at most 32 keys. Token names are 1–32 ASCII letters, digits, underscores, or hyphens.
+
+Workspace tokens use the same contract:
+
+```json
+{"id":"req_3","method":"workspace.report_metadata","params":{"workspace_id":"w1","source":"user:jj","tokens":{"jj_status":"2 changes","old":null},"ttl_ms":5000}}
+```
+
+Workspace get/list responses expose the resulting `tokens` map, and Space sidebar rows can render values such as `$jj_status`. Changes and TTL expiry emit `workspace.metadata_updated` with the latest workspace snapshot. This metadata event is available to API subscribers but does not invoke plugin event hooks.
+
+Presentation text is normalized before storage. Herdr trims surrounding whitespace, removes control characters, and caps `title`, `display_agent`, each state label, and token values at 80 characters. Empty normalized token values clear that key.
+
+`source` and `applies_to_source` are source identifiers. They must be 80 characters or fewer and may contain only ASCII letters, digits, colon, dot, underscore, and hyphen.
+
+Use `ttl_ms` for short-lived metadata. It must be between `1` and `86400000` milliseconds. Omit `ttl_ms` for metadata that should stay until replaced, cleared, or the pane/workspace closes. Presentation fields retain their existing source-scoped expiry behavior; each token updated by the call receives its own deadline. Token metadata is not restored after a server restart.
+
+Use `seq` when a hook may send updates out of order. For the same `source`, reports with a sequence number less than or equal to the last accepted sequence are accepted by the API but ignored by the pane state. A pane or workspace accepts sequenced token reports from at most 32 distinct sources during its lifetime; clearing or expiry does not release those source slots.
+
+## Event subscriptions
+
+Subscribe to events when you need a long-lived stream:
+
+```json
+{
+  "id": "sub_1",
+  "method": "events.subscribe",
+  "params": {
+    "subscriptions": [
+      { "type": "pane.agent_status_changed", "pane_id": "w1:p1", "agent_status": "blocked" }
+    ]
+  }
+}
+```
+
+The first response acknowledges the subscription. Later lines are pushed events.
+All entries must be valid: if any referenced pane does not exist, Herdr rejects
+the entire request with an error and closes the connection. Refresh the pane list
+and retry rather than assuming the other entries were subscribed.
+Lifecycle subscriptions start when the request is accepted and do not replay
+events retained before that point.
+
+Lifecycle and agent-status events are drained in bounded batches, in order within
+each subscription. Event history is not durable. If a subscriber falls behind
+the retained history, including while its subscriptions are being initialized,
+the server sends an error response with the original request `id` and
+`error.code: "events_lost"`, then closes that subscription connection instead of
+silently continuing with missing events. Other clients remain connected.
+The history is shared across event types, so an overrun is reported even when
+the evicted events might not have matched this subscription's filters.
+
+On `events_lost`, treat the cached state as stale. Open a new subscription,
+wait for `subscription_started`, and keep reading while requesting
+`session.snapshot` on another connection. Use authoritative reads to reconcile
+current state: replace the cache with the snapshot, and treat incoming events
+as invalidation signals that trigger another read. Serialize refreshes and
+refresh again if events arrive while a read is in flight.
+
+Snapshots and events have no shared sequence boundary. Ordering is guaranteed
+within each subscription entry, not across entries or relative to a snapshot,
+so do not unconditionally replay buffered event payloads onto the snapshot.
+Recovery restores current state, not the missing event history. Another
+`events_lost` requires resubscribing and reconciling again. Slow readers may
+need to increase read throughput or reduce event load.
+
+Workspace event subscriptions include `workspace.created`, `workspace.updated`, `workspace.metadata_updated`, `workspace.renamed`, `workspace.moved`, `workspace.reordered`, `workspace.closed`, and `workspace.focused`. `workspace.metadata_updated` reports token changes and TTL expiry without invoking plugin event hooks. Other workspace events describe Herdr UI/runtime lifecycle. `workspace.created` includes optional `workspace.worktree` provenance when the workspace belongs to a worktree group. `workspace.moved` includes the moved `workspace_id`, requested `insert_index`, and updated ordered `workspaces` list. `workspace.reordered` includes the atomically moved `workspace_ids`, optional `before_workspace_id`, and authoritative ordered `workspaces` list. `workspace.closed` includes a final `workspace` snapshot when Herdr can still identify it before removal.
+Tab event subscriptions include `tab.created`, `tab.closed`, `tab.focused`,
+`tab.renamed`, and `tab.moved`. `tab.moved` includes the moved `tab_id`,
+`workspace_id`, requested `insert_index`, and updated ordered `tabs` list for
+that workspace.
+Pane event subscriptions include `pane.created`, `pane.updated`, `pane.closed`, `pane.focused`,
+`pane.moved`, `pane.exited`, `pane.agent_detected`,
+`pane.output_matched`, `pane.agent_status_changed`, and `pane.scroll_changed`.
+`pane.focused` also reports manual pane selection changes from any client attached
+to this server. It does not move other clients' views, and its payload does not
+identify the client. Selecting an already-selected pane does not emit it again.
+Terminal-title changes can emit `pane.updated`, but spinner-only raw-title changes do not emit it when `terminal_title_stripped` is unchanged.
+`pane.scroll_changed` is scoped to one `pane_id` and emits `pane_id`,
+`workspace_id`, and the current `scroll` metrics whenever Herdr observes a
+changed scroll snapshot.
+Layout event subscriptions include `layout.updated`. The event carries the
+updated `PaneLayoutSnapshot` for one tab. Clients maintaining a cache with
+`session.snapshot` should use this event to refresh the affected layout through
+an authoritative read; a delayed payload may predate their latest snapshot.
+
+Worktree event subscriptions include `worktree.created`, `worktree.opened`, and `worktree.removed`. Worktree events describe Git checkout lifecycle. `worktree.created` includes the opened `workspace` and created `worktree`. `worktree.opened` includes the target `workspace`, opened `worktree`, and `already_open`. `worktree.removed` includes the `workspace_id`, removed `worktree`, and `forced`.
+
+Use `events.subscribe` for lifecycle events. Dedicated wait helpers are documented separately when a one-shot wait is supported.
+
+## Reading panes
+
+Use `pane.read` through the CLI unless you are writing a protocol client.
+
+```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` is useful for logs because it ignores soft wrapping.
+`detection` returns the bottom-buffer snapshot used by agent screen detection.
+
+## Waiting for state
+
+Use waits to coordinate agents and scripts.
+
+```bash
+herdr agent wait w1:p1 --until done
+herdr agent wait w1:p1 --until blocked
+```
+
+Agent waits observe semantic state, not arbitrary command completion.
+
+## Response shapes
+
+Successful responses look like this:
+
+```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` returns the active agent detection manifest sources and remote update diagnostics without reloading rules:
+
+```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"
+      }
+    ]
+  }
+}
+```
+
+Fields such as `last_check_unix`, `last_result`, `active_version`, `cached_remote_version`, `remote_update_result`, `remote_update_error`, `remote_last_checked_unix`, and `warning` are omitted when not available. `server.reload_agent_manifests` returns `agent_manifest_reload` with the same `manifests` item shape after reloading the in-memory rule cache.
+
+`agent.explain` evaluates the target pane's detection snapshot in the running server using the server's active manifest cache:
+
+```json
+{
+  "id": "req_2",
+  "method": "agent.explain",
+  "params": { "target": "w1:p1" }
+}
+```
+
+The response contains the same explain object printed by `herdr agent explain --json`, including the final state, manifest source and version, matched rule, evaluated rule evidence, skip-state reason, idle fallback reason, and `screen_detection_skip_reason` when a full lifecycle hook authority makes screen rules non-authoritative.
+
+Clients need a running server that supports `agent.explain`; after upgrading Herdr, restart or live-handoff the server before relying on this method.
+
+Errors look like this:
+
+```json
+{
+  "id": "req_1",
+  "error": {
+    "code": "not_found",
+    "message": "pane not found"
+  }
+}
+```
+
+## Protocol stability
+
+The client-rendered Herdr UI uses a stable endpoint generation for local and SSH
+servers. Client and server builds do not need to match. During connection setup,
+they agree on the core snapshot, screen, input, and blob codecs, and the server advertises
+the API methods and optional capabilities it supports. Saved SSH federation requires the
+`surface_interest` capability so only the selected machine streams a pane surface and the
+`health_check` capability so a quiet broken connection cannot remain Online indefinitely. A server
+without this lifecycle support stays at Attention until it is explicitly updated. Other missing methods disable
+only those actions and show a client-local notice; they do not disconnect the UI. Rejected
+or timed-out actions are also reported without ending the connection. Servers
+from before endpoint generation 1 need one final update.
+
+The numbered binary protocol remains for same-install and internal operations,
+including direct terminal attach and live handoff. Check `ping` or `herdr status`
+before using those operations across different builds. JSON API clients should
+ignore unknown fields and handle unsupported methods as normal errors.
@@ -0,0 +1,120 @@
+---
+title: Troubleshooting
+description: Diagnose common installation, terminal input, session, keybinding, and remote access problems.
+---
+
+Start with the versions and session status:
+
+```bash
+herdr -V
+herdr status
+```
+
+Also record your operating system, outer terminal name and version, whether the session is local or remote, and whether tmux is involved.
+
+## The CJK IME window is misplaced or the cursor flickers on Windows
+
+Herdr defaults to a cell-drawn cursor on native Windows and WSL because native cursors can flicker, jump, or show stale positions while ConPTY-based multiplexers repaint the screen. A cell-drawn cursor cannot provide the native cursor anchor used by Korean, Japanese, and Chinese IME composition UI.
+
+If the IME composition or candidate window appears at the wrong location, enable the native cursor:
+
+```toml
+[ui]
+host_cursor = "native"
+```
+
+Native mode restores the IME anchor but may reintroduce occasional cursor movement artifacts during active output. Return to the visually stable cursor with `host_cursor = "drawn"`, or remove the setting to use the Windows default. See [Windows support](/docs/windows-beta/) for the current limitation.
+
+## Enter, Tab, or Backspace fires twice
+
+Older versions of some terminals can emit the release of Enter, Tab, and Backspace as the same bytes as the press when an application enables Kitty keyboard event reporting. Herdr cannot distinguish those duplicate bytes after the terminal sends them.
+
+Update the outer terminal to a version that contains its upstream fix:
+
+| Terminal | Minimum fixed version |
+| --- | --- |
+| kitty | 0.33.0 |
+| foot | 1.20.0 |
+| Alacritty | 0.15.0 |
+
+This is especially common with older terminal packages from long-term-support Linux distributions. See [Herdr issue #1116](https://github.com/herdrdev/herdr/issues/1116) for the confirmed boundary captures and upstream references. If the problem remains on a current terminal version, report the exact terminal version and whether it also happens outside Herdr.
+
+## Option+Left or Option+Right inserts `;3D` or `;3C`
+
+Terminals commonly send Alt+Left and Alt+Right as the standard modified-arrow sequences `ESC[1;3D` and `ESC[1;3C`. On macOS, the outer terminal must first be configured to treat Option as Alt. If the shell does not bind these sequences, zsh may display their remaining characters as `;3D` or `;3C`. This can happen with kitty, Alacritty, and other terminals; Herdr and tmux both preserve the original modified-arrow input.
+
+Add explicit zsh bindings if you want modified arrows to perform word navigation in every terminal and nested shell:
+
+```zsh
+bindkey $'\e[1;3D' backward-word
+bindkey $'\e[1;3C' forward-word
+```
+
+Kitty can appear to work differently outside Herdr because its automatic zsh integration adds these bindings only to shells started directly by kitty, not shells created by terminal multiplexers. Follow kitty's [manual shell integration instructions](https://sw.kovidgoyal.net/kitty/shell-integration/#manual-shell-integration), or map the keys in `kitty.conf` before they reach the shell:
+
+```text
+map alt+left send_text all \x1bb
+map alt+right send_text all \x1bf
+```
+
+Herdr deliberately does not rewrite modified arrows because terminal applications may use Alt+Left and Alt+Right directly. See [Herdr issue #1370](https://github.com/herdrdev/herdr/issues/1370) for the investigation.
+
+## Herdr updated, but the running session is still old
+
+Updating the binary does not replace a compatible server that is already running. Start Herdr again to use the updated client. If you also need server-side changes from the release, check `herdr status`, then stop the session and launch Herdr again:
+
+```bash
+herdr server stop
+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
+```
+
+`Background` is normal for automatically started macOS servers and does not by itself indicate a Keychain problem. If Keychain access fails and the server was started through SSH or a background job, stop it 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.
+
+## SSH or DNS fails after macOS logout
+
+Automatically started macOS servers use a per-user service context so logging out does not leave their panes with a dead connection to macOS services. Explicit `herdr server` launches retain their caller's context.
+
+An older server can survive logout while losing user lookup and DNS. Symptoms include `No user exists for uid 501`, `Could not get manager name.`, and `curl: (6) Could not resolve host`. Logging back in does not repair that server. Stop the affected session and start Herdr from a GUI terminal in the new login. This ends live pane processes but restores the saved session layout. Live handoff preserves the source server's service context and existing pane processes. Older servers therefore need a full session restart to adopt this fix; handoff cannot repair their inherited context.
+
+If a newly started server still has this problem, check `herdr-server.log` for `could not select persistent user service context`. Herdr keeps the inherited context if the required macOS APIs are unavailable. See [Herdr issue #4100](https://github.com/herdrdev/herdr/issues/4100).
+
+## 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).
+
+## A direct keybinding does nothing
+
+The operating system or outer terminal may consume the chord before Herdr receives it. Free the chord in that layer or choose another binding. See [Keyboard](/docs/keyboard/#going-prefix-free) for known conflicts and safe defaults.
+
+## Remote attach cannot authenticate
+
+First confirm that normal OpenSSH works with `ssh <host>`. For a passphrase-protected key in a non-interactive shell, CI job, or mobile terminal, load the key into `ssh-agent` before starting remote attach. See [Persistence and remote access](/docs/persistence-remote/#remote-attach-over-ssh).
+
+## Find diagnostic logs
+
+Herdr logs live in `~/.config/herdr/` by default:
+
+```text
+herdr.log
+herdr-client.log
+herdr-server.log
+```
+
+Set `HERDR_LOG=herdr=debug` for more detail. Include the current log and rotated siblings when reporting a problem. See [Configuration](/docs/configuration/#logs).
@@ -0,0 +1,162 @@
+---
+title: Windows support
+description: Native Windows support, workflows, and known limitations.
+---
+
+Native Windows support is generally available.
+
+Herdr on Windows uses ConPTY and Windows process/runtime behavior instead of the Unix PTY model Herdr was originally built around. Most core workflows are supported, but some capabilities differ from Linux and macOS or remain platform-dependent. Windows may receive more platform-specific fixes as those remaining gaps close.
+
+Install Herdr natively on Windows with PowerShell:
+
+```powershell
+powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
+```
+
+If endpoint security blocks that fileless PowerShell command, open Command Prompt and run:
+
+```cmd
+curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del install.cmd
+```
+
+Windows builds are available through both stable and preview update channels. New installs use stable by default, and stable is recommended for normal use. Existing preview installs stay on preview until you run `herdr channel set stable`. If an older preview build rejects that command, run `herdr update` once on preview and retry. Preview provides newer, less-tested fixes from `master` and may regress; opt in with `herdr channel set preview` only when you want that tradeoff.
+
+The installer stores releases under `%USERPROFILE%\.herdr\packages\standalone\releases`, puts the active versioned release directory on PATH, keeps `%LOCALAPPDATA%\Programs\Herdr\bin` as a stable compatibility alias, and retains a small number of older releases so running processes do not block updates.
+
+For internal testing, `HERDR_MANIFEST_URL` can point the installer at a custom manifest instead of Herdr's stable or preview manifest. Set `HERDR_CHANNEL=preview` with a custom preview manifest.
+
+## Supported on Windows
+
+| Capability | Status |
+| --- | --- |
+| Local persistent sessions | supported |
+| Native panes through ConPTY | supported |
+| Windows Terminal / PowerShell app attach | supported |
+| `herdr --remote` and saved SSH machines to Linux/macOS/Windows hosts | supported; interactive attach and saved-machine setup can install or update Windows packages after confirmation; background reconnect only discovers installed packages |
+| Remote clipboard images and image-file drops | supported |
+| `cmd.exe` panes | supported |
+| Native keyboard and mouse input | supported |
+| Startup cwd and workspace labels | supported |
+| Pane launch cwd | supported |
+| Agent command discovery | supported |
+| Supported agent self-report integrations | supported |
+| Agent process-tree detection | supported |
+| Git/worktree detection from known cwd | supported |
+| System notifications and MP3 sounds | supported |
+| Plugins | preview |
+| Pane screen history | supported |
+| Nested launch override | supported |
+
+Local persistent sessions continue running after the client detaches or its terminal window closes. Servers and pane processes launched through Windows OpenSSH also survive logout; run `herdr` again to reconnect.
+
+Elevated Windows servers require an administrator client by default, including servers started through an elevated SSH login. Ordinary servers accept clients from ordinary and administrator terminals belonging to the same account; attaching never changes the server's privileges.
+
+To deliberately share elevated sessions with ordinary clients, set:
+
+```toml
+[server]
+allow_unelevated_clients = true
+```
+
+This Windows-only setting is off by default and applies when a new server starts, including automatic startup. Reloading config does not change a running server's access policy. You can instead enable sharing for one server process from an administrator terminal with `herdr server --allow-unelevated-clients` (or `herdr --session <name> server --allow-unelevated-clients` for a named session). The flag enables sharing even when the config setting is false.
+
+Either option allows ordinary local processes belonging to that account to control administrator panes; other accounts remain excluded. The flag must be supplied again after a restart unless sharing is enabled in config. Existing servers retain their previous access policy until stopped and restarted with the updated build; stopping closes their panes. Config and recovery files retain their account-based permissions.
+
+Windows agent process detection scans descendants of the pane shell and recognizes direct agents plus common command wrappers, including npm/Node and Git Bash process chains. It follows Git Bash-launched agents across emulated `exec` boundaries, but it is not the same as Unix foreground process-group detection.
+
+Windows integration installation currently supports Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, Devin CLI, OpenCode, Kilo Code CLI, Droid, Kimi Code CLI, Qoder CLI, and Antigravity CLI. Availability is narrower than on Unix; Herdr hides or rejects integrations whose install format is not supported on Windows.
+
+Plugins support `windows` as a manifest platform in preview. GitHub install, local link, build commands, actions, events, and plugin panes are best-effort on Windows. Commands are argv commands and must be Windows-compatible; Node package shims such as `npm`, `bun`, and `node` are expected to work when they are on `PATH`, while Unix-only examples using `sh` or Bash need Windows-specific alternatives. Platform filters skip unsupported build commands and return `platform_unsupported` for unsupported actions or panes.
+
+## Partial support
+
+| Capability | Status |
+| --- | --- |
+| Live cwd after shell `cd` | partial |
+| Live cwd via shell integration/OSC7 | supported |
+| Clipboard image paste to agents in local panes | terminal/agent dependent |
+| CJK IME composition anchoring | partial |
+| Prefix input-source switching (Korean IME) | partial |
+| Kitty graphics rendering | terminal dependent |
+| Host cursor rendering | partial |
+
+Herdr can launch panes in the right directory and create the initial workspace from the directory where you started Herdr. After startup, the process field Herdr can inspect does not reliably track later logical `cd` changes in PowerShell. Use Herdr integrations or prompt shell integration for live cwd reporting.
+
+During `herdr --remote`, the configured remote image paste key reads a Windows clipboard image and transfers it to the remote host. Dropping one local image file into Windows Terminal also transfers that file and pastes its remote path.
+
+Prefix input-source switching is available as an opt-in experiment for the Korean IME. It switches Hangul input to English while prefix commands are active and restores the previous mode afterward:
+
+```toml
+[experimental]
+switch_ascii_input_source_in_prefix = true
+```
+
+Other Windows IMEs are not supported by this option yet. See [Configuration](/docs/configuration/#prefix-input-source-switching).
+
+Some Windows agents can receive `ctrl+v` and read clipboard images directly. Herdr's own clipboard-image reader is not wired into local native Windows panes, so agent-native image paste remains dependent on the terminal and agent. Agent image-paste shortcuts such as `alt+v` do not add a Herdr-managed local clipboard bridge. Remote clipboard image bridging is supported separately through `herdr --remote` to Linux, macOS, and Windows hosts.
+
+Kitty graphics is enabled by default and depends on the outer terminal. Herdr emits Kitty graphics protocol output on Windows as it does on other platforms. This path has been exercised with Windows WezTerm hosting Herdr through WSL, but native Windows terminal and ConPTY combinations are not all verified. Windows Terminal does not expose the Kitty graphics path Herdr uses. Set `[terminal].kitty_graphics = false` if the outer terminal mishandles graphics output.
+
+## Known caveats
+
+### Cursor rendering
+
+Herdr relies on ConPTY for native Windows panes. The Windows terminal cursor path can expose intermediate positions while a multiplexer repaints the screen. A native cursor may flicker, jump, or briefly remain at an old position during active output. This behavior also reproduces in other native Windows terminal multiplexers and with direct VT cursor-position stress tests, so Herdr cannot eliminate it while preserving native cursor behavior.
+
+To prioritize visual stability, the default `host_cursor = "auto"` draws Herdr's cursor as terminal cell content on native Windows and WSL. Other Linux and macOS clients continue to use the native terminal cursor. The drawn Windows cursor is steady and non-blinking, but it does not provide the outer terminal's native blink, shape, or cursor color.
+
+Windows does not use a drawn cursor to position IME composition and candidate UI. Korean, Japanese, or Chinese IME UI may therefore appear at the wrong location. If this affects you, opt back into the outer terminal cursor:
+
+```toml
+[ui]
+host_cursor = "native"
+```
+
+Native mode restores the IME anchor, but it can reintroduce occasional cursor flicker, jumps, or stale cursor positions during active output.
+
+### Keyboard and mouse
+
+Windows terminals do not all report modified keys in the same shape. Herdr preserves mouse reporting and `ctrl+j` in Windows Terminal and Alacritty on Windows. The native Windows input path also preserves physical key presses, repeats, releases, standalone Escape, and `shift+enter` through default ConPTY panes. Modified keys still depend on the outer terminal reporting a distinct key event; if it reports `shift+enter` as plain Enter, Herdr can only forward plain Enter.
+
+Windows packages include Microsoft's current app-local ConPTY runtime because the system ConPTY on older Windows 10 builds drops Kitty keyboard protocol sequences used by agents such as Kimi and Pi. Set `HERDR_WINDOWS_CONPTY=system` before starting Herdr only when diagnosing a compatibility problem with the bundled runtime.
+
+## Copy and paste
+
+Herdr's pane text copy works on Windows. Drag-select text inside a pane to copy through Herdr.
+
+For text paste, use `ctrl+shift+v` in Windows Terminal. Multiline text paste is bracketed so shells and agent prompts receive it as one paste instead of submitting each line separately. Hold `shift` and right-click to use the outer terminal paste action instead of sending the click through Herdr.
+
+Windows clients also recover text when WezTerm wraps a complete sequence of Win32 character press/release pairs in raw paste markers. Mixed text and incomplete reports are not decoded by this compatibility rule. Literal clipboard text consisting entirely of matching Win32 reports is indistinguishable from this encoding and is decoded too.
+
+## Not supported on Windows
+
+| Capability | Status |
+| --- | --- |
+| Direct terminal attach (`herdr terminal attach`) | unsupported |
+| Live server handoff | unsupported |
+| Unix file-descriptor handoff | unsupported |
+| Unix foreground process groups | unsupported |
+| Herdr clipboard image bridge in local native panes | unsupported |
+| Signed binary / SmartScreen avoidance | unsupported |
+
+From Windows Terminal, use the same remote command as Linux and macOS:
+
+```powershell
+herdr --remote workbox
+```
+
+The target host can run Linux, macOS, or Windows. On Windows hosts, remote attach reuses a compatible package from `PATH` or the active managed release. Interactive direct attach and saved-machine setup prompt before installing or updating the complete package when needed. Background saved reconnect only discovers installed packages and cannot prompt for installation or updates. Herdr uses the installed Windows OpenSSH client and your SSH configuration. Windows OpenSSH does not use Herdr's Unix control-socket reuse, so key authentication through Windows `ssh-agent` is recommended to avoid repeated prompts during remote setup.
+
+Windows updates run through the Windows installer and update the active versioned release path. New terminals and reconnected SSH sessions receive that path; start Herdr there to use the updated client. Compatible running servers keep their panes alive. Restart a server later only when you need server-side changes from the release. Live handoff is Unix-only.
+
+## Reporting Windows issues
+
+Include:
+
+- Herdr version.
+- Windows version.
+- Terminal app.
+- Shell, such as PowerShell or cmd.
+- Whether you used a named `HERDR_SESSION`.
+- Relevant Herdr logs.
+- Exact steps to reproduce.
--- a/Show More
+++ b/Show More