diff --git a/.huskies/README.md b/.huskies/README.md
index b39cec8c..2fd9ae01 100644
--- a/.huskies/README.md
+++ b/.huskies/README.md
@@ -72,10 +72,79 @@ Consult `specs/tech/STACK.md` for project-specific quality gates.
 | `status` | Get story details, ACs, git state |
 | `get_story_todos` | List unchecked acceptance criteria |
 | `check_criterion` | Mark an AC as done |
-| `run_tests` | Start test suite (async, returns immediately) |
-| `get_test_result` | Poll for test completion |
+| `run_tests` | Start test suite (blocks until complete) |
 | `git_status` | Worktree git status |
 | `git_add` | Stage files |
 | `git_commit` | Commit staged changes |
 | `git_diff` | View changes |
 | `git_log` | View commit history |
+
+---
+
+## 7. Deployment Modes
+
+Huskies has three modes, all from the same binary:
+
+### Standard (single project)
+
+```
+huskies [--port 3001] /path/to/project
+```
+
+Full server: web UI, MCP endpoint, chat bot, agent pool, pipeline. One project per instance.
+
+### Headless Build Agent
+
+```
+huskies --rendezvous ws://host:port/crdt-sync
+```
+
+Connects to an existing huskies instance as a worker node. Syncs the CRDT, claims work from the pipeline, runs agents. No web UI, no chat — just a build worker. Use this to add more compute to a project by running extra containers.
+
+### Gateway (multi-project)
+
+```
+huskies --gateway [--port 3000] /path/to/config
+```
+
+Lightweight proxy that sits in front of multiple project containers. Reads a `projects.toml` that maps project names to container URLs:
+
+```toml
+[projects.huskies]
+url = "http://huskies:3001"
+
+[projects.robot-studio]
+url = "http://robot-studio:3002"
+```
+
+The gateway presents a unified MCP surface to the chat agent. All tool calls are proxied to the active project's container. Gateway-specific tools:
+
+| Tool | Purpose |
+|------|---------|
+| `switch_project` | Change the active project |
+| `gateway_status` | Show active project and list all registered projects |
+| `gateway_health` | Health check all containers |
+
+### Example: multi-project Docker Compose
+
+```yaml
+services:
+  gateway:
+    image: huskies
+    command: ["huskies", "--gateway", "--port", "3000", "/workspace"]
+    ports:
+      - "127.0.0.1:3000:3000"
+    depends_on: [huskies, robot-studio]
+
+  huskies:
+    image: huskies
+    volumes:
+      - /path/to/huskies:/workspace
+
+  robot-studio:
+    image: huskies
+    environment:
+      - HUSKIES_PORT=3002
+    volumes:
+      - /path/to/robot-studio:/workspace
+```