From d1c88cd96ed10cc5c751e17874369010555bd506 Mon Sep 17 00:00:00 2001 From: Emanuele <106186915+OneStepAt4time@users.noreply.github.com> Date: Tue, 12 May 2026 15:16:53 +0200 Subject: [PATCH] docs: add ag run hang troubleshooting note MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: add fallback note if ag run hangs without creating session - getting-started: add troubleshooting callout pointing to step-by-step setup - Refs #3247 — ag run hangs on first external tester session --- README.md | 2 ++ docs/getting-started.md | 2 ++ 2 files changed, 4 insertions(+) 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. +
With a global install (optional) 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 ` | 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.*