feat: add native windows beta support

3 files changed, 85 insertions, 3 deletions

diff --git a/docs/next/website/src/content/docs/install.mdx b/docs/next/website/src/content/docs/install.mdx
index 6322c8e0..41139821 100644
--- a/docs/next/website/src/content/docs/install.mdx
+++ b/docs/next/website/src/content/docs/install.mdx
@@ -1,9 +1,9 @@
 ---
 title: Install Herdr
-description: Install, update, and verify Herdr on Linux and macOS.
+description: Install, update, and verify Herdr on Linux, macOS, and Windows beta.
 ---
 
-Herdr ships as a single binary for Linux and macOS.
+Herdr ships as a single binary for Linux and macOS. Native Windows support is beta.
 
 ## Install
 
@@ -120,6 +120,7 @@ Choose the asset that matches your system:
 | Linux aarch64 | `herdr-linux-aarch64` |
 | macOS Intel | `herdr-macos-x86_64` |
 | macOS Apple silicon | `herdr-macos-aarch64` |
+| Windows x86_64 beta | `herdr-windows-x86_64.exe` |
 
 Make it executable and move it somewhere on your PATH.
 
@@ -130,4 +131,4 @@ mv herdr-linux-x86_64 ~/.local/bin/herdr
 
 ## Requirements
 
-Herdr supports Linux and macOS. Native Windows support is not available yet; use Herdr inside WSL for now.
+Herdr supports Linux and macOS. Native Windows support is beta; see [Windows beta](/docs/windows-beta/) for supported workflows and known limitations.
diff --git a/docs/next/website/src/content/docs/persistence-remote.mdx b/docs/next/website/src/content/docs/persistence-remote.mdx
index 3e25dd69..1f60f964 100644
--- a/docs/next/website/src/content/docs/persistence-remote.mdx
+++ b/docs/next/website/src/content/docs/persistence-remote.mdx
@@ -92,6 +92,8 @@ herdr --remote workbox
 
 Remote attach supports Linux and macOS hosts on x86_64 and aarch64. Herdr checks the remote platform, prefers a matching `herdr` already on the remote `PATH`, then checks `~/.local/bin/herdr`. If no matching binary exists, interactive runs prompt to install one to `~/.local/bin/herdr`; non-interactive runs fail instead of modifying the host. If `~/.local/bin` is not on the remote `PATH`, Herdr warns after install.
 
+Native Windows `herdr --remote` is not part of the Windows beta. From Windows, SSH into the server and run `herdr` there.
+
 By default, `herdr --remote` runs the bridge through a temporary SSH config that includes your SSH config first, then adds fallback keepalive settings. Existing user keepalive settings win. Set `[remote].manage_ssh_config = false` to use plain `ssh` without Herdr's generated bridge config.
 
 By default, remote attach uses the normal restart/stop flow if it needs to replace or restart a running remote server. To opt into experimental live handoff for a supported running remote server, pass `--handoff`:
@@ -122,6 +124,8 @@ herdr --remote workbox --session agents
 
 Full Herdr attach opens the whole workspace UI. Direct attach opens one server-owned terminal in your current terminal.
 
+Direct terminal attach is Unix-only in the Windows beta.
+
 Attach by agent target:
 
 ```bash
diff --git a/docs/next/website/src/content/docs/windows-beta.mdx b/docs/next/website/src/content/docs/windows-beta.mdx
new file mode 100644
index 00000000..1d6e929f
--- /dev/null
+++ b/docs/next/website/src/content/docs/windows-beta.mdx
@@ -0,0 +1,77 @@
+---
+title: Windows beta
+description: Native Windows support status, supported workflows, and known limitations.
+---
+
+Native Windows support is beta. It runs as the same Herdr version as Linux and macOS, but some Unix features are intentionally unavailable on Windows.
+
+## Supported in beta
+
+| Capability | Status |
+| --- | --- |
+| Local persistent sessions | beta |
+| Native panes through ConPTY | beta |
+| Windows Terminal / PowerShell app attach | beta |
+| `cmd.exe` panes | beta |
+| Startup cwd and workspace labels | beta |
+| Pane launch cwd | beta |
+| Agent command discovery | beta |
+| Agent self-report integrations | beta |
+| Agent process-tree detection | beta |
+| Git/worktree detection from known cwd | beta |
+| 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.
+
+## Partial support
+
+| Capability | Status |
+| --- | --- |
+| Live cwd after shell `cd` | partial |
+| Live cwd via shell integration/OSC7 | beta |
+| Clipboard image paste to agents | unverified |
+| CJK hidden-cursor reveal | beta |
+| Kitty graphics rendering | unverified |
+
+Herdr can launch panes in the right directory and can create the initial workspace from the directory where you started Herdr. PowerShell directory changes after startup are different: the process field Herdr can inspect does not reliably track later logical `cd` changes. Use Herdr integrations or prompt shell integration for live cwd reporting.
+
+Windows Terminal may support image paste paths for specific agents, but Herdr's own clipboard-image reader is not wired on Windows yet. Treat `alt+v` image paste as unverified until the Windows clipboard bridge is implemented and tested. Remote clipboard image bridging is separate and remains tied to Unix/macOS `herdr --remote`.
+
+Kitty graphics remains experimental and is not claimed as Windows-supported yet. Leave `experimental.kitty_graphics = false` unless you are specifically testing image rendering in Windows Terminal.
+
+## Not supported on Windows beta
+
+| Capability | Status |
+| --- | --- |
+| Direct terminal attach | unsupported |
+| `herdr --remote` from the Windows binary | unsupported |
+| Live server handoff | unsupported |
+| Unix file-descriptor handoff | unsupported |
+| Unix foreground process groups | unsupported |
+| Remote clipboard image bridge | unsupported |
+| Prefix input-source switching | unsupported |
+| Signed binary / SmartScreen avoidance | unsupported |
+
+For remote work from Windows, SSH into the server and run `herdr` there:
+
+```powershell
+ssh you@server
+herdr
+```
+
+That mode runs Herdr on the remote host. Native Windows `herdr --remote` is not part of the beta.
+
+Windows updates may require stopping the running Herdr server and starting it again. Live handoff is Unix-only.
+
+## Reporting Windows beta 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.