diff --git a/README.md b/README.md
index 8dd0396..a9de297 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,11 @@ git clone https://github.com/basefoundry/base.git
 git clone https://github.com/basefoundry/base-demo.git
 ```
 
+For a first Base setup, `basectl onboard base-demo` is the recommended guided path.
+It wraps the setup, profile, doctor, and project-discovery flow for new Base
+users. Run `basectl onboard base-demo --dry-run` to preview the steps without
+changing local state.
+
 From the `base-demo` repository root on a machine where Base is already set up:
 
 ```bash
diff --git a/tests/validate.sh b/tests/validate.sh
index bc37599..e8e55ce 100755
--- a/tests/validate.sh
+++ b/tests/validate.sh
@@ -475,6 +475,21 @@ grep -Fq 'basectl setup base-demo  # macOS only' README.md || {
   exit 1
 }
 
+grep -Fq 'basectl onboard base-demo' README.md || {
+  printf 'README.md does not document basectl onboard in Quick Start.\n' >&2
+  exit 1
+}
+
+grep -Fq 'basectl onboard base-demo --dry-run' README.md || {
+  printf 'README.md does not document basectl onboard --dry-run in Quick Start.\n' >&2
+  exit 1
+}
+
+grep -Fq 'recommended guided path' README.md || {
+  printf 'README.md does not describe basectl onboard as the recommended guided path.\n' >&2
+  exit 1
+}
+
 grep -Fq 'basectl activate base-demo  # macOS only' README.md || {
   printf 'README.md does not annotate activate as macOS-only in Quick Start.\n' >&2
   exit 1