From 79933b0fdb4d27a0cfd90b577e75de1572e6f6fd Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <codeforester@gmail.com>
Date: Thu, 2 Jul 2026 10:41:13 -0700
Subject: [PATCH] Demonstrate basectl docs in walkthrough

---
 .github/workflows/tests.yml |  3 +++
 README.md                   |  2 ++
 demo/demo.sh                | 11 +++++++++++
 tests/demo_test.bats        |  6 ++++++
 tests/validate.sh           | 20 ++++++++++++++++++++
 5 files changed, 42 insertions(+)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 3375dc9..0c5998d 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -115,6 +115,9 @@ jobs:
       - name: Build base-demo
         run: ../base/bin/basectl build base-demo --workspace ..
 
+      - name: Show Base docs URL
+        run: ../base/bin/basectl docs --show-url
+
       - name: Run base-demo non-interactively
         run: ../base/bin/basectl demo base-demo --workspace .. -- --non-interactive
 
diff --git a/README.md b/README.md
index a9de297..0bf42fc 100644
--- a/README.md
+++ b/README.md
@@ -70,6 +70,7 @@ basectl logs --limit 3
 basectl history --project base-demo --limit 5
 basectl build base-demo
 basectl demo base-demo  # macOS only
+basectl docs --show-url
 basectl export-context base-demo --format markdown --print
 ```
 
@@ -106,6 +107,7 @@ The commands above exercise the complete Base project loop:
   show the local audit trail for recent Base activity.
 - `basectl build base-demo` runs the default build target (`info`) declared in the manifest.
 - `basectl demo base-demo` runs the macOS project-owned walkthrough.
+- `basectl docs --show-url` prints the Base documentation home page URL without opening a browser.
 - `basectl export-context base-demo --format markdown --print` prints the
   repository AI context bundle for assistant handoff.
 
diff --git a/demo/demo.sh b/demo/demo.sh
index 1dbd8c9..4a1f4e8 100755
--- a/demo/demo.sh
+++ b/demo/demo.sh
@@ -469,6 +469,16 @@ export_context_step() {
   pause
 }
 
+docs_step() {
+  local output
+
+  step 16 "Documentation Shortcut"
+  output="$(capture_command "$BASE_DEMO_BASECTL" docs --show-url)"
+  printf '%s\n' "$output"
+  require_contains "docs command" "$output" "github.com/basefoundry/base"
+  pause
+}
+
 closing_summary() {
   printf '\nWalkthrough Summary\n\n'
   printf 'Manifest fields exercised: brewfile, mise, python, health, ide, activate, commands, test, build, demo, and artifacts.\n'
@@ -501,6 +511,7 @@ main() {
   build_step
   demo_step
   export_context_step
+  docs_step
   closing_summary
 }
 
diff --git a/tests/demo_test.bats b/tests/demo_test.bats
index e5f337e..5b4cd7c 100755
--- a/tests/demo_test.bats
+++ b/tests/demo_test.bats
@@ -224,6 +224,9 @@ case "$*" in
     printf '# AI Context Export: base-demo\n'
     printf '## .ai-context/manifest.md\n'
     ;;
+  docs\ --show-url)
+    printf 'https://github.com/basefoundry/base#readme\n'
+    ;;
   *)
     printf 'unexpected basectl args: %s\n' "$*" >&2
     exit 1
@@ -314,6 +317,8 @@ EOF
   [[ "$output" == *"python-api build target validated"* ]]
   [[ "$output" == *"AI Context Export"* ]]
   [[ "$output" == *"AI Context Export: base-demo"* ]]
+  [[ "$output" == *"Documentation Shortcut"* ]]
+  [[ "$output" == *"github.com/basefoundry/base"* ]]
   [[ "$output" == *"Manifest fields exercised:"* ]]
   [[ "$output" == *"docs/representative-environment.md"* ]]
   [[ "$output" == *"banyanlabs"* ]]
@@ -349,4 +354,5 @@ EOF
   grep -Eq "^basectl build base-demo python-api --workspace .+$" "$state_file"
   grep -Eq "^basectl demo base-demo --workspace .+ --dry-run -- --non-interactive$" "$state_file"
   grep -Eq "^basectl export-context base-demo --workspace .+ --format markdown --print$" "$state_file"
+  grep -Eq "^basectl docs --show-url$" "$state_file"
 }
diff --git a/tests/validate.sh b/tests/validate.sh
index e8e55ce..c8c31d7 100755
--- a/tests/validate.sh
+++ b/tests/validate.sh
@@ -490,6 +490,26 @@ grep -Fq 'recommended guided path' README.md || {
   exit 1
 }
 
+grep -Fq 'basectl docs --show-url' README.md || {
+  printf 'README.md does not document basectl docs --show-url in Quick Start.\n' >&2
+  exit 1
+}
+
+grep -Fq 'Show Base docs URL' .github/workflows/tests.yml || {
+  printf '.github/workflows/tests.yml does not show the Base docs URL in CI.\n' >&2
+  exit 1
+}
+
+grep -Fq 'basectl docs --show-url' .github/workflows/tests.yml || {
+  printf '.github/workflows/tests.yml does not run basectl docs --show-url in CI.\n' >&2
+  exit 1
+}
+
+grep -Fq 'github.com/basefoundry/base' demo/demo.sh || {
+  printf 'demo/demo.sh does not validate the Base docs URL host.\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