docs: add ag run hang troubleshooting note

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>
 

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.*