docs: prefer wsl over native windows stuff (#11637)

packages/web/astro.config.mjs

@@ -85,6 +85,7 @@ export default defineConfig({
         "network",
         "enterprise",
         "troubleshooting",
+        "windows-wsl",
         "1-0",
         {
           label: "Usage",

packages/web/src/content/docs/index.mdx

@@ -89,6 +89,10 @@ You can also install it with the following commands:
 
 #### Windows
 
+:::tip[Recommended: Use WSL]
+For the best experience on Windows, we recommend using [Windows Subsystem for Linux (WSL)](/docs/windows-wsl). It provides better performance and full compatibility with OpenCode's features.
+:::
+
 - **Using Chocolatey**
 
   ```bash

packages/web/src/content/docs/troubleshooting.mdx

@@ -136,6 +136,12 @@ On Windows, OpenCode Desktop requires the Microsoft Edge **WebView2 Runtime**. I
 
 ---
 
+### Windows: General performance issues
+
+If you're experiencing slow performance, file access issues, or terminal problems on Windows, try using [WSL (Windows Subsystem for Linux)](/docs/windows-wsl). WSL provides a Linux environment that works more seamlessly with OpenCode's features.
+
+---
+
 ### Notifications not showing
 
 OpenCode Desktop only shows system notifications when:

packages/web/src/content/docs/web.mdx

@@ -21,6 +21,10 @@ This starts a local server on `127.0.0.1` with a random available port and autom
 If `OPENCODE_SERVER_PASSWORD` is not set, the server will be unsecured. This is fine for local use but should be set for network access.
 :::
 
+:::tip[Windows Users]
+For the best experience, run `opencode web` from [WSL](/docs/windows-wsl) rather than PowerShell. This ensures proper file system access and terminal integration.
+:::
+
 ---
 
 ## Configuration

packages/web/src/content/docs/windows-wsl.mdx

@@ -0,0 +1,113 @@
+---
+title: Windows (WSL)
+description: Run OpenCode on Windows using WSL for the best experience.
+---
+
+import { Steps } from "@astrojs/starlight/components"
+
+While OpenCode can run directly on Windows, we recommend using [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) for the best experience. WSL provides a Linux environment that works seamlessly with OpenCode's features.
+
+:::tip[Why WSL?]
+WSL offers better file system performance, full terminal support, and compatibility with development tools that OpenCode relies on.
+:::
+
+---
+
+## Setup
+
+<Steps>
+
+1. **Install WSL**
+
+   If you haven't already, [install WSL](https://learn.microsoft.com/en-us/windows/wsl/install) using the official Microsoft guide.
+
+2. **Install OpenCode in WSL**
+
+   Once WSL is set up, open your WSL terminal and install OpenCode using one of the [installation methods](/docs/).
+
+   ```bash
+   curl -fsSL https://opencode.ai/install | bash
+   ```
+
+3. **Use OpenCode from WSL**
+
+   Navigate to your project directory (access Windows files via `/mnt/c/`, `/mnt/d/`, etc.) and run OpenCode.
+
+   ```bash
+   cd /mnt/c/Users/YourName/project
+   opencode
+   ```
+
+</Steps>
+
+---
+
+## Desktop App + WSL Server
+
+If you prefer using the OpenCode Desktop app but want to run the server in WSL:
+
+1. **Start the server in WSL** with `--hostname 0.0.0.0` to allow external connections:
+
+   ```bash
+   opencode serve --hostname 0.0.0.0 --port 4096
+   ```
+
+2. **Connect the Desktop app** to `http://localhost:4096`
+
+:::note
+If `localhost` does not work in your setup, connect using the WSL IP address instead (from WSL: `hostname -I`) and use `http://<wsl-ip>:4096`.
+:::
+
+:::caution
+When using `--hostname 0.0.0.0`, set `OPENCODE_SERVER_PASSWORD` to secure the server.
+
+```bash
+OPENCODE_SERVER_PASSWORD=your-password opencode serve --hostname 0.0.0.0
+```
+
+:::
+
+---
+
+## Web Client + WSL
+
+For the best web experience on Windows:
+
+1. **Run `opencode web` in the WSL terminal** rather than PowerShell:
+
+   ```bash
+   opencode web --hostname 0.0.0.0
+   ```
+
+2. **Access from your Windows browser** at `http://localhost:<port>` (OpenCode prints the URL)
+
+Running `opencode web` from WSL ensures proper file system access and terminal integration while still being accessible from your Windows browser.
+
+---
+
+## Accessing Windows Files
+
+WSL can access all your Windows files through the `/mnt/` directory:
+
+- `C:` drive → `/mnt/c/`
+- `D:` drive → `/mnt/d/`
+- And so on...
+
+Example:
+
+```bash
+cd /mnt/c/Users/YourName/Documents/project
+opencode
+```
+
+:::tip
+For the smoothest experience, consider cloning/copying your repo into the WSL filesystem (for example under `~/code/`) and running OpenCode there.
+:::
+
+---
+
+## Tips
+
+- Keep OpenCode running in WSL for projects stored on Windows drives - file access is seamless
+- Use VS Code's [WSL extension](https://code.visualstudio.com/docs/remote/wsl) alongside OpenCode for an integrated development workflow
+- Your OpenCode config and sessions are stored within the WSL environment at `~/.local/share/opencode/`