docs: capture Windows compatibility guidance

Author: benvinegar

AGENTS.md

@@ -118,6 +118,16 @@ CLI input
 - For CLI, config, or pager work: make sure the relevant source invocation still works (`diff`, `show`, `patch`, or `pager`).
 - Preserve current interaction model unless the user asks to change it explicitly.
 
+## Windows compatibility
+
+- Normalize filesystem paths in tests with Node `path` helpers (`resolve`, `join`, `relative`, or `normalize`) instead of expecting hard-coded `/tmp/...` or POSIX separators.
+- Keep command/API payload expectations intentional: normalize real local filesystem paths, but preserve user-provided or protocol paths when the product is supposed to pass them through unchanged.
+- Avoid POSIX shell syntax in GitHub Actions steps that run on Windows; invoke `bun test ...` or scripts directly rather than relying on `${VAR:-fallback}` expansion.
+- Disable Git CRLF conversion before checkout in Windows CI (`core.autocrlf false`) so format checks see repository line endings.
+- Do not force Unix PTY/TTY smoke coverage onto Windows. Prefer the full non-PTY unit/integration surface there, and keep terminal-native PTY smoke tests on Unix runners.
+- Be careful with Bun timers and sockets on Windows: `timeout.unref?.()` can prevent expected test timers from firing, and some low-level websocket/net close cases may need coverage at a less crash-prone layer.
+- Avoid creating fixtures with filenames that are invalid or unreliable on Windows (for example paths containing tabs or other special characters) unless the test is explicitly Unix-only.
+
 ## releases
 
 - Maintain the top-level `CHANGELOG.md` as the source of truth for user-visible changes.