diff --git a/README.md b/README.md
index 0bf42fc..069d9e4 100644
--- a/README.md
+++ b/README.md
@@ -88,8 +88,8 @@ The commands above exercise the complete Base project loop:
   health for read-only CI pipelines, including Ubuntu/Linux checks.
 - `basectl repo check .` validates the standard repository baseline files.
 - `basectl workspace status --manifest workspace.yaml.example` shows a
-  workspace-level view of the expected `base`, `base-demo`, and
-  `base-bash-libs` peer repositories.
+  workspace-level view of the expected `base`, `base-demo`, optional
+  `base-platform-tools`, and optional `base-bash-libs` peer repositories.
 - `basectl run base-demo --list` shows the manifest-declared project commands.
 - `basectl run base-demo hello` runs the `hello` command from the project root.
 - `basectl run base-demo env` shows Base runtime metadata such as `BASE_OS`,
diff --git a/demo/demo.sh b/demo/demo.sh
index 4a1f4e8..97a66f9 100755
--- a/demo/demo.sh
+++ b/demo/demo.sh
@@ -220,6 +220,9 @@ discovery_step() {
   if [[ -f "$BASE_DEMO_ROOT/workspace.yaml.example" ]]; then
     output="$(capture_command "$BASE_DEMO_BASECTL" workspace status --workspace "$BASE_DEMO_WORKSPACE" --manifest "$BASE_DEMO_ROOT/workspace.yaml.example")"
     printf '%s\n' "$output"
+    if [[ "$output" == *"base-platform-tools"* ]]; then
+      printf "\nbase-platform-tools is an optional Base companion; when present, Base adds its bin/ directory after Base's own bin/.\n"
+    fi
     require_contains "workspace status" "$output" "$BASE_DEMO_PROJECT"
   else
     run_observed_command "$BASE_DEMO_BASECTL" workspace status --workspace "$BASE_DEMO_WORKSPACE"
diff --git a/tests/demo_test.bats b/tests/demo_test.bats
index 5b4cd7c..e220b73 100755
--- a/tests/demo_test.bats
+++ b/tests/demo_test.bats
@@ -74,6 +74,7 @@ case "$*" in
     printf 'WORKSPACE base-demo-reference\n'
     printf 'base present healthy\n'
     printf 'base-demo present healthy\n'
+    printf 'base-platform-tools optional missing\n'
     printf 'base-bash-libs optional missing\n'
     ;;
   setup\ base-demo\ --manifest\ *\ --dry-run\ --no-notify)
@@ -246,6 +247,7 @@ EOF
   [[ "$output" == *"base-demo Walkthrough"* ]]
   [[ "$output" == *"Workspace Discovery"* ]]
   [[ "$output" == *"base-demo-reference"* ]]
+  [[ "$output" == *"base-platform-tools is an optional Base companion"* ]]
   [[ "$output" == *"Setup Contract"* ]]
   [[ "$output" == *"bats-core"* ]]
   [[ "$output" == *"required_ports:"* ]]
diff --git a/tests/validate.sh b/tests/validate.sh
index c8c31d7..2789b4d 100755
--- a/tests/validate.sh
+++ b/tests/validate.sh
@@ -510,6 +510,31 @@ grep -Fq 'github.com/basefoundry/base' demo/demo.sh || {
   exit 1
 }
 
+grep -Fq 'base-platform-tools' workspace.yaml.example || {
+  printf 'workspace.yaml.example does not list base-platform-tools.\n' >&2
+  exit 1
+}
+
+grep -Fq 'https://github.com/basefoundry/base-platform-tools.git' workspace.yaml.example || {
+  printf 'workspace.yaml.example does not list the base-platform-tools GitHub URL.\n' >&2
+  exit 1
+}
+
+grep -A4 'name: base-platform-tools' workspace.yaml.example | grep -Fq 'required: false' || {
+  printf 'workspace.yaml.example does not mark base-platform-tools as optional.\n' >&2
+  exit 1
+}
+
+grep -Fq 'base-platform-tools is an optional Base companion' demo/demo.sh || {
+  printf 'demo/demo.sh does not explain the optional base-platform-tools companion.\n' >&2
+  exit 1
+}
+
+grep -Fq 'base-platform-tools' README.md || {
+  printf 'README.md does not document optional base-platform-tools workspace status.\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
diff --git a/workspace.yaml.example b/workspace.yaml.example
index 95b64f3..9f463f6 100644
--- a/workspace.yaml.example
+++ b/workspace.yaml.example
@@ -9,6 +9,11 @@ repos:
     default_branch: main
     required: true
 
+  - name: base-platform-tools
+    url: https://github.com/basefoundry/base-platform-tools.git
+    default_branch: main
+    required: false
+
   - name: base-demo
     url: https://github.com/basefoundry/base-demo.git
     default_branch: main