From 54a887a579cf59bc9866af57617256ef4e61d1b0 Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <codeforester@gmail.com>
Date: Thu, 2 Jul 2026 10:58:55 -0700
Subject: [PATCH] Document future Go Cobra CLI boundary

---
 docs/representative-environment.md | 13 +++++++++++++
 tests/validate.sh                  | 15 +++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/docs/representative-environment.md b/docs/representative-environment.md
index c7b28e8..e4697d1 100644
--- a/docs/representative-environment.md
+++ b/docs/representative-environment.md
@@ -22,6 +22,19 @@ The three repos have distinct roles:
 Labs. Its services should be boring on purpose: health checks, hello responses,
 metadata, documented ports, and simple build/test paths.
 
+## Future Go/Cobra CLI Boundary
+
+A non-trivial Go/Cobra CLI does not belong in the current baseline demo. The
+baseline already includes a tiny Go HTTP API so Base can demonstrate Go build
+and test orchestration without adding another required tool shape to first-run
+setup.
+
+If Base needs a deeper CLI example later, prefer a separate `base-demo-go`
+repository or a clearly optional advanced slice that is not required by
+`BASE_DEMO_ENV=baseline`, Quick Start, or read-only CI. Any later
+implementation should use Go's standard toolchain and Cobra only when command
+structure is complex enough to justify it.
+
 ## Target Stack
 
 The target stack is broad enough to feel real and small enough to inspect:
diff --git a/tests/validate.sh b/tests/validate.sh
index 2789b4d..6d74b2f 100755
--- a/tests/validate.sh
+++ b/tests/validate.sh
@@ -470,6 +470,21 @@ grep -Fq 'docs/linux-support.md' README.md || {
   exit 1
 }
 
+grep -Fq '## Future Go/Cobra CLI Boundary' docs/representative-environment.md || {
+  printf 'docs/representative-environment.md does not document the future Go/Cobra CLI boundary.\n' >&2
+  exit 1
+}
+
+grep -Fq 'base-demo-go' docs/representative-environment.md || {
+  printf 'docs/representative-environment.md does not name base-demo-go as the future Go/Cobra split option.\n' >&2
+  exit 1
+}
+
+grep -Fq 'does not belong in the current baseline demo' docs/representative-environment.md || {
+  printf 'docs/representative-environment.md does not keep Go/Cobra out of the current baseline demo.\n' >&2
+  exit 1
+}
+
 grep -Fq 'basectl setup base-demo  # macOS only' README.md || {
   printf 'README.md does not annotate setup as macOS-only in Quick Start.\n' >&2
   exit 1