docs(readme): document the wait-for readiness gate

README.md

@@ -25,6 +25,28 @@ Commands:
 
 Exit codes: 0 success, 1 operational error, 2 daemon unreachable, 3 config invalid.
 
+## Waiting on a dependency
+
+A server can declare a precondition that must hold before it is started:
+
+    wait-for {
+        path "~/.orbstack/run/docker.sock"
+        timeout "180s"
+        interval "1s"
+    }
+
+Exactly one condition per block — `path "<p>"` (the path exists),
+`tcp "<host:port>"` (a connection succeeds), or `command "<c>"` with optional
+`args` (the process exits 0). `timeout` defaults to 120s and `interval` to 1s.
+
+While waiting the server reports state `waiting`, and `xy status <name>` shows
+which condition it is blocked on and for how long. If the timeout expires the
+server is marked `failed` and is never spawned.
+
+Waiting does **not** consume the restart budget: a slow dependency costs
+patience, not retries. This is what stops a Docker-backed server from being
+marked failed at login while the Docker daemon is still starting.
+
 ## Start on login (macOS)
 
     xy service install     # write the LaunchAgent, load it, start the daemon