Add guided local setup workflow

README.md

@@ -50,20 +50,11 @@ cd NetEngine
 # 2. Install dependencies
 poetry install
 
-# 3. Verify host prerequisites and requested world subnets
-poetry run netengine doctor --spec examples/minimal.yaml
-
-# 4. Start local Postgres + pgmq (includes pgmq extension pre-installed)
-docker compose up -d postgres
-
-# 5. Apply migrations
-poetry run python -m netengine.utils.run_migrations
-
-# 6. Boot a minimal world
-poetry run netengine up examples/minimal.yaml
+# 3. Run guided first-time local setup
+poetry run netengine setup local examples/minimal.yaml
 ```
 
-If you only want host/container checks before configuring Postgres, run `poetry run netengine doctor --skip-db`. Add `--spec examples/minimal.yaml` (or pass the spec as a positional argument) to include subnet-overlap checks for `spec.substrate.networks[*].subnet` before bootstrapping. Check status at any time:
+`netengine setup local` runs the pre-Postgres host checks, starts the required compose services, waits for Postgres health, applies migrations, reruns spec-aware doctor checks, and only then calls the existing `netengine up` bootstrap path. If you only want host/container checks before configuring Postgres, run `poetry run netengine doctor --skip-db`. Add `--spec examples/minimal.yaml` (or pass the spec as a positional argument) to include subnet-overlap checks for `spec.substrate.networks[*].subnet` before bootstrapping. Check status at any time:
 
 ```bash
 poetry run netengine status

docs/alpha-quickstart.md

@@ -16,15 +16,11 @@ This guide is the focused alpha operator path. The root `README.md` keeps the hi
 git clone https://github.com/Forebase/NetEngine.git
 cd NetEngine
 poetry install
-poetry run netengine doctor --skip-db --spec examples/minimal.yaml
-docker compose up -d postgres
-poetry run python -m netengine.utils.run_migrations
-poetry run netengine doctor --spec examples/minimal.yaml
-poetry run netengine up examples/minimal.yaml
+poetry run netengine setup local examples/minimal.yaml
 poetry run netengine status
 ```
 
-Use `poetry run netengine doctor --spec examples/minimal.yaml` before bootstrapping a world to check host prerequisites plus Docker subnet conflicts against `spec.substrate.networks[*].subnet`. Use `NETENGINE_MOCK=true` when you want to exercise orchestration and spec validation without creating Docker, DNS, PKI, or identity resources.
+Use `poetry run netengine setup local examples/minimal.yaml` for the guided first-time path: it runs host checks that are safe before Postgres starts, starts compose services, waits for database health, applies migrations, performs spec-aware doctor checks, and stops before `netengine up` if required checks fail. Use `NETENGINE_MOCK=true` when you want to exercise orchestration and spec validation without creating Docker, DNS, PKI, or identity resources.
 
 ## Pre-release mock smoke test
 

docs/runbook.md

@@ -41,42 +41,20 @@ That's it — all 10 phases run end-to-end and runtime state is written to
 
 This brings up the real persistence and identity layers.
 
-### 1. Start backing services
-
-```bash
-poetry run netengine doctor --skip-db
-docker compose up -d
-poetry run netengine doctor
-```
-
-This starts:
-- `netengine_postgres` on port 5432 (with pgmq extension)
-- Keycloak on port 8080 (platform identity, used in Phase 4)
-
-The doctor command checks Python, Docker/Compose, required ports, writable runtime paths, database connectivity, pgmq, and stale Docker/state conflicts. Wait for postgres to be healthy:
-
-```bash
-docker compose ps          # all services should show "healthy"
-```
-
-### 2. Apply migrations
-
-```bash
-psql postgresql://netengine:dev_password@localhost:5432/netengine \
-  -f migrations/001_initial.sql
-```
-
-Set the database URL for subsequent commands:
+### 1. Guided setup and bootstrap
 
 ```bash
 export NETENGINE_DB_URL="postgresql://netengine:dev_password@localhost:5432/netengine"
+poetry run netengine setup local examples/minimal.yaml
 ```
 
-### 3. Bootstrap the world
+The guided setup replaces the former manual sequence of `doctor`, `docker compose up`, database waiting, migrations, another doctor run, and `netengine up`. It runs pre-Postgres host checks first, starts the required compose services, waits for `netengine_postgres` to become healthy, applies migrations, runs spec-aware doctor/database checks, and stops before bootstrapping if required checks fail.
 
-```bash
-poetry run netengine up examples/minimal.yaml
-```
+The setup workflow provides remediation hints for common blockers:
+- **Subnet conflicts:** remove conflicting Docker networks with `docker network rm <name>` or choose non-overlapping subnets in the world spec.
+- **Port conflicts:** stop the process/container using the published port or change the compose/spec port.
+- **Docker name conflicts:** run `netengine down`, `docker compose down`, or remove stale containers before retrying.
+- **Database failures:** inspect `docker compose ps postgres` and `docker logs netengine_postgres`, verify `NETENGINE_DB_URL`, then rerun `netengine setup local examples/minimal.yaml`.
 
 This runs all phases sequentially. Each phase reports `completed successfully`
 when done. Runtime state is saved after each phase; the run is resumable if