diff --git a/docs/cli/onboard.md b/docs/cli/onboard.md
index af20fafb3495..b844bac78eac 100644
--- a/docs/cli/onboard.md
+++ b/docs/cli/onboard.md
@@ -47,10 +47,16 @@ openclaw onboard --mode remote --remote-url wss://gateway-host:18789
 `--modern` starts the Crestodian conversational onboarding preview. Without
 `--modern`, `openclaw onboard` keeps the classic onboarding flow.
 
-On a fresh install where the active config file is missing or has no authored
-settings (empty or metadata-only), bare `openclaw` also starts the classic
-onboarding flow. Once a config file has authored settings, bare `openclaw`
-opens Crestodian instead.
+In an interactive terminal, bare `openclaw` (no subcommand) routes by config
+state:
+
+- If the active config file is missing or has no authored settings (empty or
+  metadata-only), it starts this classic onboarding flow.
+- If the config file exists but fails validation, it starts
+  [Crestodian](/cli/crestodian) for repair.
+- If the config file is valid, it opens the normal agent TUI, either locally
+  or connected to a reachable configured Gateway. On a configured install,
+  reach Crestodian with `/crestodian` inside the TUI or `openclaw crestodian`.
 
 Plaintext `ws://` is accepted for loopback, private IP literals, `.local`, and
 Tailnet `*.ts.net` gateway URLs. For other trusted private-DNS names, set