docs: add tmux as strongly recommended prerequisite and document install-tmux

README.md

@@ -21,6 +21,23 @@ Taskplane turns your coding project into an AI-managed task board. You define ta
 
 Taskplane is a [pi package](https://github.com/badlogic/pi-mono). You need [Node.js](https://nodejs.org/) ≥ 20 and [pi](https://github.com/badlogic/pi-mono) installed first.
 
+### Prerequisites
+
+| Dependency | Required | Notes |
+|-----------|----------|-------|
+| [Node.js](https://nodejs.org/) ≥ 20 | Yes | Runtime |
+| [pi](https://github.com/badlogic/pi-mono) | Yes | Agent framework |
+| [Git](https://git-scm.com/) | Yes | Version control, worktrees |
+| **tmux** | **Strongly recommended** | Required for `/orch` parallel execution |
+
+**tmux** is needed for the orchestrator to spawn parallel worker sessions. Without it, `/orch` will not work. On Windows, Taskplane can install it for you:
+
+```bash
+taskplane install-tmux
+```
+
+On macOS: `brew install tmux` · On Linux: `sudo apt install tmux` (or your distro's package manager)
+
 ### Option A: Global Install (all projects)
 
 ```bash
@@ -138,6 +155,7 @@ Orchestrator lanes execute tasks through task-runner under the hood, so `/task`
 |---------|-------------|
 | `taskplane init` | Scaffold project config (interactive or `--preset`) |
 | `taskplane doctor` | Validate installation and config |
+| `taskplane install-tmux` | Install or upgrade tmux for Git Bash (Windows) |
 | `taskplane version` | Show version info |
 | `taskplane dashboard` | Launch the web dashboard |
 | `taskplane uninstall` | Remove Taskplane project files and optionally uninstall package (`--package`) |

docs/how-to/use-tmux-for-visibility.md

@@ -80,7 +80,13 @@ For standalone `/task`, prefer default subprocess mode unless you specifically n
 
 ### `tmux: command not found`
 
-Install tmux and verify:
+Install tmux:
+
+- **Windows (Git Bash):** `taskplane install-tmux`
+- **macOS:** `brew install tmux`
+- **Linux:** `sudo apt install tmux`
+
+Verify:
 
 ```bash
 tmux -V

docs/reference/commands.md

@@ -346,6 +346,25 @@ Scaffold Taskplane project files (`.pi/`, agents, task templates).
 
 Validate installation and project configuration.
 
+On Windows, if tmux is not found, doctor suggests running `taskplane install-tmux`.
+
+### `taskplane install-tmux [options]`
+
+Install or upgrade tmux for Git Bash on Windows. Downloads tmux and libevent packages from the official MSYS2 package repository and places binaries in `~/bin/`.
+
+**Options**
+
+- `--check` — show current tmux status without installing
+- `--force` — reinstall even if already up to date
+
+**Notes**
+
+- Windows only. On macOS/Linux, prints a redirect to `brew install tmux` or `apt install tmux`.
+- Requires Node.js ≥ 21.7 (for native zstd decompression).
+- Requires Git Bash (provides `tar` and the MSYS2 runtime).
+- Installs to `~/bin/` which is on PATH in Git Bash by default. No admin rights needed.
+- Safe to re-run for upgrades.
+
 ### `taskplane version`
 
 Show package and environment version details.

docs/tutorials/install.md

@@ -7,9 +7,37 @@ This tutorial gets Taskplane running in a project and verifies that `/task` and
 - Node.js **20+**
 - [pi](https://github.com/badlogic/pi-mono)
 - Git
+- **tmux** (strongly recommended — required for `/orch` parallel execution)
 
-Optional (for tmux-based orchestration visibility):
-- tmux
+### Installing tmux
+
+tmux is needed for the orchestrator to spawn parallel worker sessions in isolated worktrees. Without it, `/orch` will not work.
+
+**Windows (Git Bash):**
+
+```bash
+taskplane install-tmux
+```
+
+This downloads tmux from the official [MSYS2](https://packages.msys2.org/packages/tmux) package repository and installs it into `~/bin/`. No admin rights or external tools needed. To upgrade later, run the same command with `--force`.
+
+**macOS:**
+
+```bash
+brew install tmux
+```
+
+**Linux (Debian/Ubuntu):**
+
+```bash
+sudo apt install tmux
+```
+
+Verify tmux is available:
+
+```bash
+tmux -V
+```
 
 ---
 
@@ -218,9 +246,13 @@ pi install npm:taskplane
 
 Run `taskplane init` from the project root.
 
-### tmux warning in doctor
+### tmux missing or not found
+
+tmux is required for `/orch` parallel execution. Install it:
 
-tmux is optional unless you use `spawn_mode: tmux` in orchestrator config.
+- **Windows:** `taskplane install-tmux`
+- **macOS:** `brew install tmux`
+- **Linux:** `sudo apt install tmux`
 
 ---