From 02f07502872faed89a63f881de9ec4f10275c141 Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <codeforester@gmail.com>
Date: Tue, 2 Jun 2026 17:03:43 -0700
Subject: [PATCH] Document the full Base demo workflow

---
 README.md | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 353e39b..885888e 100644
--- a/README.md
+++ b/README.md
@@ -15,18 +15,52 @@ git clone https://github.com/codeforester/base.git
 git clone https://github.com/codeforester/base-demo.git
 ```
 
-From a machine where Base is already set up:
+From the `base-demo` repository root on a machine where Base is already set up:
 
 ```bash
 basectl projects list
 basectl setup base-demo
 basectl check base-demo
 basectl doctor base-demo
+basectl repo check .
+basectl run base-demo --list
 basectl run base-demo hello
 basectl test base-demo
+basectl activate base-demo
 basectl demo base-demo
 ```
 
+The commands above exercise the complete Base project loop:
+
+- `basectl projects list` proves the repository is discoverable from the
+  workspace.
+- `basectl setup base-demo` reconciles the project manifest, Brewfile, and
+  project virtual environment.
+- `basectl check base-demo` and `basectl doctor base-demo` validate the local
+  project environment.
+- `basectl repo check .` validates the standard repository baseline files.
+- `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 test base-demo` runs the manifest-declared test command.
+- `basectl activate base-demo` starts a project shell with the activation
+  source applied.
+- `basectl demo base-demo` runs the project-owned walkthrough.
+
+Expected command output includes:
+
+```text
+$ basectl run base-demo --list
+hello
+
+$ basectl run base-demo hello
+hello from base-demo
+BASE_PROJECT=base-demo
+BASE_DEMO_ENV=baseline
+
+$ basectl test base-demo
+Repository baseline is present.
+```
+
 ## Repository Shape
 
 - `base_manifest.yaml` declares the project name, activation source, command,