From 827e5626c02687dc71d0ebcaf7138a87ae80ea59 Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com>
Date: Thu, 8 Oct 2026 10:57:03 +0530
Subject: [PATCH] docs: document base-cli-demo as the reference consumer

---
 README.md                   |  6 ++++++
 docs/adoption-evidence.md   | 15 +++++++++++++--
 docs/consumer-quickstart.md |  6 ++++++
 docs/index.md               |  4 ++++
 mkdocs.yml                  |  1 +
 5 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index dbaff40..dec51ff 100644
--- a/README.md
+++ b/README.md
@@ -69,6 +69,12 @@ if __name__ == "__main__":
 Run it with `python hello.py --name Ada`. The full lifecycle and configuration
 options are documented below.
 
+For a complete maintained example, see the independent
+[`base-cli-demo`](https://github.com/basefoundry/base-cli-demo) reference
+consumer. It is versioned separately (`0.1.0`) and currently tests the released
+`base-cli>=0.4.3,<0.5` line; its 0.5.0 upgrade is tracked in
+[base-cli-demo#47](https://github.com/basefoundry/base-cli-demo/issues/47).
+
 Release builds, TestPyPI rehearsals, and protected PyPI publication are
 documented in [`docs/releasing.md`](https://basefoundry.github.io/base-cli/releasing/). The package exposes
 `base_cli.__version__`, which matches the distribution version.
diff --git a/docs/adoption-evidence.md b/docs/adoption-evidence.md
index 56e6899..2307006 100644
--- a/docs/adoption-evidence.md
+++ b/docs/adoption-evidence.md
@@ -22,12 +22,23 @@ written permission from that team.
 | Category | What it proves | Source | Public claim allowed |
 | --- | --- | --- | --- |
 | Reference fixture | A maintained consumer shape remains compatible | [`compatibility/README.md`](https://github.com/basefoundry/base-cli/blob/main/compatibility/README.md) and CI | “The fixture passed.” |
+| Maintained reference/learning consumer | A complete external repository exercises the public consumer boundary | [`base-cli-demo`](https://github.com/basefoundry/base-cli-demo) and its dated CI | “The demo passed its declared framework line.” It is not an adopter claim. |
 | Compatibility run | A specific revision/version passed a dated matrix | `base-cli-compatibility-evidence-<run-id>` artifact | “Version X passed run Y.” |
 | External adopter | A real independent team completed an agreed outcome | Permissioned adopter record | Only the approved case-study facts |
 
 Reference fixtures must remain separate packages with their own metadata and
-tests. Base, base-demo, and other adjacent repositories are explicitly
-excluded from the independent-adopter count.
+tests. Base, base-demo, `base-cli-demo`, and other adjacent repositories are
+explicitly excluded from the independent-adopter count.
+
+`base-cli-demo` is a maintained reference and learning consumer, versioned
+independently (`0.1.0`). Its CI demonstrates that a real consumer can exercise
+the public facade, lifecycle, output, error, and optional-integration paths for
+the exact framework dependency line it declares; it is not an independent
+adopter result or a substitute for a dated compatibility-fixture artifact.
+While its current released line is `base-cli>=0.4.3,<0.5`, the 0.5.0 upgrade is
+tracked in [base-cli-demo#47](https://github.com/basefoundry/base-cli-demo/issues/47)
+and must be green against the published framework before being described as
+0.5.0 evidence.
 
 ## Adopter program
 
diff --git a/docs/consumer-quickstart.md b/docs/consumer-quickstart.md
index e2487fb..bec575c 100644
--- a/docs/consumer-quickstart.md
+++ b/docs/consumer-quickstart.md
@@ -5,6 +5,12 @@ command, one option, and the `run_app()` process boundary. It is suitable for
 a temporary consumer project and does not require Typer, Rich, YAML, or any
 private repository layout.
 
+For a maintained, runnable consumer with nested commands, structured errors,
+and optional Typer, Rich, and OpenTelemetry scenarios, continue to
+[`base-cli-demo`](https://github.com/basefoundry/base-cli-demo). The demo is
+reference/learning evidence rather than an independent adopter, and it is
+versioned separately from the framework.
+
 ## Install and create the command
 
 Use an isolated virtual environment when trying the recipe. Activate it using
diff --git a/docs/index.md b/docs/index.md
index 4f67c56..b5e916b 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -93,5 +93,9 @@ Continue with the framework guides:
   compatibility policy.
 - [Reference applications](https://github.com/basefoundry/base-cli/tree/main/examples)
   for complete consumer patterns.
+- [`base-cli-demo`](https://github.com/basefoundry/base-cli-demo) for the
+  maintained end-to-end reference consumer, optional integration scenarios,
+  and runnable documentation examples. It is versioned independently and its
+  current released dependency line is `base-cli>=0.4.3,<0.5`.
 - [Installation and packaging](adopter-readiness.md) for dependency extras,
   distribution checks, and release guidance.
diff --git a/mkdocs.yml b/mkdocs.yml
index 7116d05..560c374 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -34,6 +34,7 @@ nav:
   - Getting started:
       - Framework choice: framework-choice.md
       - Consumer quickstart: consumer-quickstart.md
+      - Reference consumer: https://github.com/basefoundry/base-cli-demo
       - Adopter readiness: adopter-readiness.md
       - Adoption evidence: adoption-evidence.md
       - Compatibility dashboard: compatibility-dashboard.md