diff --git a/README.md b/README.md
index 86a7f3de2..8984a46d7 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ cd agent-orchestrator && bash scripts/setup.sh
 cd ~/your-project && ao init --auto && ao start
 ```
 
-Dashboard opens at http://localhost:3000
+Dashboard opens at http://localhost:3000 (port configurable via `port:` in config)
 
 ## Overview
 
@@ -99,7 +99,7 @@ ao spawn my-project
 # Command-line dashboard
 ao status
 
-# Web dashboard
+# Web dashboard (default port 3000, configurable in agent-orchestrator.yaml)
 open http://localhost:3000
 ```
 
@@ -142,7 +142,7 @@ reactions:
 Basic configuration in `agent-orchestrator.yaml`:
 
 ```yaml
-port: 3000
+port: 3000  # Dashboard port (each project needs a unique port if running multiple)
 
 defaults:
   runtime: tmux
@@ -214,7 +214,7 @@ See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues and solutions.
 **Common issues:**
 
 - Terminal not working → node-pty rebuild (automatic via postinstall hook)
-- Port in use → Kill existing server or change port in config
+- Port in use → Change `port:` in config or kill existing server (`lsof -ti:3000 | xargs kill`)
 - Config not found → Run `ao init` from your project directory
 
 ## Contributing
diff --git a/SETUP.md b/SETUP.md
index 90fc998a2..79f70fc0b 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -102,7 +102,7 @@ The wizard will prompt you for:
 
 1. **Data directory** - Where to store session metadata (default: `~/.agent-orchestrator`)
 2. **Worktree directory** - Where to create isolated workspaces (default: `~/.worktrees`)
-3. **Dashboard port** - Web interface port (default: `9847`)
+3. **Dashboard port** - Web interface port (default: `3000`)
 4. **Runtime plugin** - Session runtime (default: `tmux`)
 5. **Agent plugin** - AI coding assistant (default: `claude-code`)
 6. **Workspace plugin** - Workspace isolation method (default: `worktree`)
@@ -148,7 +148,7 @@ The absolute minimum needed:
 ```yaml
 dataDir: ~/.agent-orchestrator
 worktreeDir: ~/.worktrees
-port: 9847
+port: 3000
 
 projects:
   my-app:
@@ -437,20 +437,22 @@ source ~/.zshrc
 echo $LINEAR_API_KEY
 ```
 
-### "Port 3000 already in use"
+### "Port already in use"
 
-**Problem:** Another service is using port 9847.
+**Problem:** Another service is using the dashboard port (default 3000).
 
 **Solution:**
 
 ```bash
-# Change port in agent-orchestrator.yaml
+# Option 1: Change port in agent-orchestrator.yaml
 port: 3001
 
-# Or find and kill the process using port 9847
+# Option 2: Find and kill the process using the port
 lsof -ti:3000 | xargs kill
 ```
 
+**Note:** When running multiple projects, each needs a different `port:` value in its config.
+
 ### "Workspace creation failed"
 
 **Problem:** Orchestrator can't create worktrees or clones.
@@ -730,7 +732,7 @@ projects:
 
 Three ways:
 
-1. **Dashboard** - `ao start` then visit http://localhost:9847
+1. **Dashboard** - `ao start` then visit http://localhost:3000 (or your configured `port:`)
 2. **CLI status** - `ao status` (text-based dashboard)
 3. **Attach to session** - `ao open <session-name>` (live terminal)
 
@@ -771,9 +773,11 @@ ao session ls --json | jq -r '.[] | select(.status == "merged") | .id' | xargs -
 Yes! Each orchestrator instance should have:
 
 - Different data directory (`dataDir`)
-- Different port (`port`)
+- Different dashboard port (`port`) — e.g., 3000 for project A, 3001 for project B
 - Different config file
 
+Terminal WebSocket ports are auto-detected by default, so you typically only need to set `port:` differently. If you need explicit control, you can also set `terminalPort:` and `directTerminalPort:` per config.
+
 Useful for:
 
 - Separating projects
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 9c0150310..32a247333 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -40,7 +40,7 @@ pnpm build
 cd packages/web
 pnpm dev
 
-# Open http://localhost:3000
+# Open http://localhost:3000 (or your configured port)
 ```
 
 ### Project Structure
diff --git a/examples/README.md b/examples/README.md
index 6fb7e34ee..2365c0590 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -108,6 +108,6 @@ After copying an example:
 1. **Edit the config** - Update repo paths, team IDs, etc.
 2. **Validate** - Run `ao start` to check for config errors
 3. **Spawn an agent** - Try `ao spawn project-id ISSUE-123`
-4. **Monitor** - Use `ao status` or open the dashboard at http://localhost:3000
+4. **Monitor** - Use `ao status` or open the dashboard (default http://localhost:3000, configurable via `port:` in config)
 
 See [SETUP.md](../SETUP.md) for detailed configuration reference and troubleshooting.
diff --git a/packages/core/README.md b/packages/core/README.md
index cdbf8c058..29d6c34eb 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -108,7 +108,9 @@ Loads and validates `agent-orchestrator.yaml`:
 
 - `dataDir` — where session metadata lives (~/.agent-orchestrator)
 - `worktreeDir` — where workspaces are created (~/.worktrees)
-- `port` — web dashboard port (default 3000)
+- `port` — web dashboard port (default 3000, set different values for multiple projects)
+- `terminalPort` — terminal WebSocket port (auto-detected if not set)
+- `directTerminalPort` — direct terminal WebSocket port (auto-detected if not set)
 - `defaults` — default plugins (runtime, agent, workspace, notifiers)
 - `projects` — per-project config (repo, path, branch, symlinks, reactions, agentRules)
 - `notifiers` — notification channel config (Slack webhooks, etc.)