diff --git a/README.md b/README.md
index 6c01ce304..94e7a70ae 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,8 @@ npx --package=@onestepat4time/aegis ag run "Build a login page with email/passwo
 
 That's it. `ag run` bootstraps config, starts the server, creates a session, and streams output to your terminal.
 
+> **If `ag run` hangs** without creating a session, use the step-by-step setup below instead — it separates server start from session creation and gives clearer error output.
+
 <details>
 <summary>With a global install (optional)</summary>
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 853539552..5d7d1e186 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -32,6 +32,8 @@ If the server is already running, `ag run` skips bootstrap and start — goes st
 | `--port <number>` | Server port override |
 | `--no-stream` | Don't stream output; print curl commands instead |
 
+> **Troubleshooting:** If `ag run` hangs without creating a session, fall back to the step-by-step setup below. It separates server start from session creation and gives clearer error output.
+
 ---
 
 *Everything below is for advanced setups — most users can stop here.*