Document future Go Cobra CLI boundary

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:

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