diff --git a/README.md b/README.md
index 2032857..72b4aa1 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,8 @@
   ·
   <a href="./ROADMAP.md">Roadmap</a>
   ·
+  <a href="./TROUBLESHOOTING.md">Troubleshooting</a>
+  ·
   <a href="https://discord.gg/5TUQKqFWd">UltraWorkers Discord</a>
 </p>
 
@@ -212,6 +214,7 @@ Claw Code is built in the open alongside the broader UltraWorkers toolchain:
 
 We welcome contributions! Before filing an issue or pull request:
 
+- **Troubleshooting:** See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for common issues and recovery steps
 - **For security issues:** See [SECURITY.md](./SECURITY.md)
 - **For bug reports / features:** Check [ROADMAP.md](./ROADMAP.md) to see if it's already pinpointed
 - **How to file a pinpoint:** See [CONTRIBUTING.md](./CONTRIBUTING.md) for the exact format
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
new file mode 100644
index 0000000..4403cff
--- /dev/null
+++ b/TROUBLESHOOTING.md
@@ -0,0 +1,31 @@
+# Troubleshooting
+
+## Upstream stream-init failures (`500 empty_stream`)
+
+**Symptom:** claw-code exits with `500 empty_stream: upstream stream closed before first payload` or similar upstream stream-init error.
+
+**Root cause:** Upstream provider (Anthropic, OpenAI, other) closed the HTTP connection before sending the first response payload. Common causes:
+- Transient network issue between claw-code and provider
+- Provider overload / temporary service degradation
+- Authentication token expired or invalid
+- Rate limit exceeded (even if not visible in response headers)
+
+**Mitigation:**
+1. **Check credentials:** Verify `claw whoami` shows the expected provider and account. Re-authenticate if expired.
+2. **Wait and retry:** Provider transient issues usually resolve within 30-60 seconds. Wait a minute, then retry the same command.
+3. **Check provider status:** Visit the provider's status page (e.g., status.anthropic.com, status.openai.com).
+4. **Reduce request size:** If the prompt is large, try a smaller request first to isolate stream-init from context-window failures.
+5. **Check network:** Ensure your network connection is stable. If behind a proxy, verify proxy allows streaming responses.
+
+**When to escalate:**
+- If stream-init failures persist >10 minutes across multiple requests
+- If `claw whoami` fails to authenticate
+- If no provider status page shows degradation
+
+**Related pinpoint:** #290 (typed stream-init failure envelope — future improvement for better diagnostics)
+
+---
+
+## Other common failures
+
+*[placeholder for future sections: context-window errors, tool-use failures, session corruption, auto-compaction loops]*