diff --git a/AGENTS.md b/AGENTS.md
index c6bc1ef7fd3..9cafd6af355 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,3 +3,11 @@
 ## Worktree Safety
 
 Always use the primary working directory (the worktree) for all file reads and edits. Never follow absolute paths from subagent results that point to the main repo.
+
+## Cross-Platform Support
+
+Orca targets macOS, Linux, and Windows. Keep all platform-dependent behavior behind runtime checks:
+
+- **Keyboard shortcuts**: Never hardcode `e.metaKey`. Use a platform check (`navigator.userAgent.includes('Mac')`) to pick `metaKey` on Mac and `ctrlKey` on Linux/Windows. Electron menu accelerators should use `CmdOrCtrl`.
+- **Shortcut labels in UI**: Display `⌘` / `⇧` on Mac and `Ctrl+` / `Shift+` on other platforms.
+- **File paths**: Use `path.join` or Electron/Node path utilities — never assume `/` or `\`.