docs: clarify README install option requirements (#945)

* Clarify README install option requirements
* docs: add Windows PowerShell syntax for Docker sandbox option

Split Option 2 into Linux/Mac and Windows (PowerShell) code blocks to address
cross-platform shell syntax differences. The original Unix-style export syntax
doesn't work on Windows CMD or PowerShell.

* docs: refine install commands across platforms
* docs: move Windows PowerShell instructions to separate README

---------

Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: chuckbutkus <chuck@openhands.dev>
Co-authored-by: enyst <engel.nyst@gmail.com>

AGENTS.md

@@ -431,6 +431,7 @@ When adding code that needs a new string, decide up front which rule it falls un
 
 - README expectation: keep the first section as a concrete, chronological from-scratch quickstart for running this frontend against a real `openhands-agent-server` (clone, install prerequisites, optional `.env`, run `npm run dev`).
 - Keep README user-focused and move contributor/developer-specific workflows (`dev:safe`, mock mode, detailed env vars/build-test notes) into `DEVELOPMENT.md`.
+- Windows-specific command syntax (PowerShell) lives in `README.windows.md`. When changing install / Docker sandbox instructions in `README.md`, update `README.windows.md` in the same PR to keep them in sync.
 - `scripts/dev-safe.mjs` uses `uvx` for temporary agent-server installation — no permanent `uv tool install` needed. Environment variables (highest precedence first):
   - `OH_AGENT_SERVER_LOCAL_PATH` — absolute path to a local `software-agent-sdk` checkout. Runs the local checkout via `uvx` with `--with-editable` for `openhands-sdk`/`openhands-tools`/`openhands-workspace` and `--reinstall` for `openhands-agent-server`, so SDK edits are picked up on restart. Highest precedence.
   - `OH_AGENT_SERVER_GIT_REF` — git commit SHA or branch name (takes precedence over version)

README.md

@@ -60,24 +60,34 @@ agent-canvas
 
 ### Option 2: With a Docker Sandbox
 
+**Prerequisites**:
+
+- Docker: Docker Desktop on macOS/Windows, or Docker Engine/Docker Desktop on Linux.
+- A host directory for `PROJECTS_PATH` containing the project folders you want the agent to access. Create it before starting the container.
+
+**macOS / Linux:**
 ```sh
 docker pull ghcr.io/openhands/agent-canvas:1.0.0-alpha.10
 
-export PROJECTS_PATH=~/projects  # directory containing your project folders
+export PROJECTS_PATH="$HOME/projects"  # directory containing your project folders
+mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"
 
 docker run -it --rm \
   -p 8000:8000 \
-  -v ~/.openhands:/home/openhands/.openhands \
-  -v ${PROJECTS_PATH}:/projects \
+  -v "$HOME/.openhands:/home/openhands/.openhands" \
+  -v "${PROJECTS_PATH}:/projects" \
   ghcr.io/openhands/agent-canvas:1.0.0-alpha.10
 ```
 
+**Windows (PowerShell / Windows Terminal):** See [README.windows.md](./README.windows.md) for the equivalent commands.
+
 The agent will be able to access any project under `PROJECTS_PATH`.
 
-
-
 ### Option 3: From Source
 
+> [!WARNING]
+> This runs the agent-server directly on the machine you're installing on — the agent will have full access to your filesystem!
+
 **Prerequisites**: Node.js 22.12.x or later, `npm`, `uv` (for running the agent server via `uvx`)
 
 ```sh

README.windows.md

@@ -0,0 +1,27 @@
+# Windows quickstart (PowerShell)
+
+This doc contains **Windows-specific** command syntax for running Agent Canvas with the **Docker sandbox**.
+
+For the main install options and overall context, see [README.md](./README.md).
+
+## Option 2: With a Docker Sandbox (Windows)
+
+**Prerequisites**:
+
+- Docker Desktop for Windows
+- A host directory for `PROJECTS_PATH` containing the project folders you want the agent to access (create it before starting the container)
+
+```powershell
+docker pull ghcr.io/openhands/agent-canvas:1.0.0-alpha.10
+
+$env:PROJECTS_PATH = Join-Path $HOME "projects"  # directory containing your project folders
+New-Item -ItemType Directory -Force -Path $env:PROJECTS_PATH, (Join-Path $env:USERPROFILE ".openhands") | Out-Null
+
+docker run -it --rm `
+  -p 8000:8000 `
+  -v "$($env:USERPROFILE)\.openhands:/home/openhands/.openhands" `
+  -v "$($env:PROJECTS_PATH):/projects" `
+  ghcr.io/openhands/agent-canvas:1.0.0-alpha.10
+```
+
+The agent will be able to access any project under `PROJECTS_PATH`.