fix: add best-effort windows plugin support

3 files changed, 25 insertions, 10 deletions

diff --git a/docs/next/website/src/content/docs/plugins.mdx b/docs/next/website/src/content/docs/plugins.mdx
index 652b44a0..d6db3ede 100644
--- a/docs/next/website/src/content/docs/plugins.mdx
+++ b/docs/next/website/src/content/docs/plugins.mdx
@@ -140,6 +140,12 @@ 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.
+
 ## Panes
 
 Manifest pane `placement` defaults to `overlay`, which opens a temporary zoomed
@@ -152,6 +158,11 @@ 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.
 
+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:
diff --git a/docs/next/website/src/content/docs/socket-api.mdx b/docs/next/website/src/content/docs/socket-api.mdx
index 4f8071ad..2bfe41df 100644
--- a/docs/next/website/src/content/docs/socket-api.mdx
+++ b/docs/next/website/src/content/docs/socket-api.mdx
@@ -313,7 +313,7 @@ Link a local plugin manifest:
 `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/example.worktree-bootstrap","installed_unix_ms":1780000000000}}}
+{"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
@@ -324,7 +324,7 @@ id = "example.worktree-bootstrap"
 name = "Worktree Bootstrap"
 version = "0.1.0"
 description = "Prepare new worktrees"
-platforms = ["linux", "macos"]
+platforms = ["linux", "macos", "windows"]
 
 [[build]]
 command = ["bun", "install"]
@@ -335,13 +335,6 @@ title = "Bootstrap worktree"
 contexts = ["workspace"]
 command = ["bun", "run", "bootstrap.ts"]
 
-[[actions]]
-id = "bootstrap-win"
-title = "Bootstrap worktree (Windows)"
-contexts = ["workspace"]
-platforms = ["windows"]
-command = ["powershell.exe", "-ExecutionPolicy", "Bypass", "-File", "bootstrap.ps1"]
-
 [[events]]
 on = "worktree.created"
 command = ["bun", "run", "bootstrap.ts"]
@@ -383,6 +376,9 @@ Actions are resolved from the linked manifest. `plugin.action.list` returns all
 {"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
@@ -434,7 +430,8 @@ returns `plugin_pane_focused`; close returns `plugin_pane_closed`.
 
 ## Socket transport
 
-Herdr uses newline-delimited JSON over a Unix domain socket.
+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:
 
@@ -470,6 +467,10 @@ Resolution order:
 
 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`.
diff --git a/docs/next/website/src/content/docs/windows-beta.mdx b/docs/next/website/src/content/docs/windows-beta.mdx
index 762da9ef..d64353c3 100644
--- a/docs/next/website/src/content/docs/windows-beta.mdx
+++ b/docs/next/website/src/content/docs/windows-beta.mdx
@@ -33,11 +33,14 @@ For internal beta testing, `HERDR_MANIFEST_URL` can point the installer at a cus
 | Agent self-report integrations | beta |
 | Agent process-tree detection | beta |
 | Git/worktree detection from known cwd | beta |
+| Plugins | preview |
 | Pane screen history | beta |
 | Nested launch override | beta |
 
 Windows agent process detection scans descendants of the pane shell and recognizes direct agents plus common command wrappers. It is useful for Codex, Claude, and similar agents, but it is not the same as Unix foreground process-group detection.
 
+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 |