docs: link Beacon as the v2 learning path

CHANGELOG.md

@@ -7,7 +7,10 @@ and versions are tracked in the repo-root `VERSION` file.
 
 ## [Unreleased]
 
-No unreleased changes yet.
+### Documentation
+
+- Link the pinned Base Bash Demo v0.1.2 learning path from the README,
+  documentation index, and v2 quickstart, and refresh the consumer ledger.
 
 ## [2.2.1] - 2026-10-08
 

README.md

@@ -71,10 +71,15 @@ Production-shaped reference applications and transparent startup benchmarks
 are in [`examples/reference-apps`](examples/reference-apps) and
 [`benchmarks/reference-apps.sh`](benchmarks/reference-apps.sh).
 The isolated first-party
-[`base-bash-libs-demo`](https://github.com/basefoundry/base-bash-libs-demo)
-repository consumes the canonical release bundle and runs its Beacon
-application as a downstream compatibility canary. It is regression evidence,
-not an independent-adoption claim.
+[`base-bash-libs-demo`](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/README.md)
+repository is a five-minute, offline Beacon application that shows the v2
+CLI, configuration, lifecycle, and cleanup contracts in a complete consumer.
+Start with its [pinned five-minute tutorial](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/five-minute-tutorial.md),
+then read [why Base Bash](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/why-base-bash-libs.md)
+and the [adoption decision guide](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/should-i-use-base-bash-libs.md).
+The repository also consumes the canonical release bundle as a downstream
+compatibility canary. It is regression evidence, not an independent-adoption
+claim.
 For the rest of the documentation, use the map near the end of this README.
 
 ## When to reach for Base Bash

docs/README.md

@@ -8,6 +8,10 @@ when updating an existing script.
 ## Start here
 
 - [Five-minute quickstart](v2/quickstart.md)
+- [Beacon reference consumer](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/README.md): a complete, offline application walkthrough
+  using the released v2 API. Continue with the [five-minute tutorial](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/five-minute-tutorial.md),
+  [why Base Bash](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/why-base-bash-libs.md),
+  and the [adoption decision guide](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/should-i-use-base-bash-libs.md).
 - [Architecture and execution model](v2/architecture.md)
 - [API reference](api-reference.md) and [v2 API contract](v2-api-contract.md)
 - [Configuration, lifecycle, and status contracts](v2/architecture.md#application-contract)

docs/consumer-validation-status.md

@@ -42,7 +42,7 @@ results count as independent adoption evidence.
 | --- | --- | --- | --- | --- | --- |
 | Base | First-party direct consumer | published [v1.8.0](https://github.com/basefoundry/base/releases/tag/v1.8.0), commit `26b9af5` | CI and source-checkout workflows pin GA commit `b424376` (v2.0.0) | PR [#1936](https://github.com/basefoundry/base/pull/1936) passed Python/pylint, integration, security, BATS, Ubuntu source-checkout, macOS smoke, and branch policy; v1.8.0 release preflight and publication passed | GA pin and release pass |
 | Base Demo | First-party representative consumer | merged [#217](https://github.com/basefoundry/base-demo/pull/217) at `fb7a2b6` | CI and source-checkout workflows pin GA commit `b424376` (v2.0.0) | Local full validation and hosted validate, Ubuntu, and source-checkout checks passed | GA pin and validation pass |
-| Base Bash Demo | First-party isolated reference consumer | released [v0.1.0](https://github.com/basefoundry/base-bash-libs-demo/releases/tag/v0.1.0) at `7acf3c6`; docs and vendor target the verified v2.2.0 bundle while the v2.2.1 upstream patch is prepared | Commits the verified canonical v2.2.0 bundle, lock, checksum manifest, provenance, and SPDX SBOM; candidate checks use an explicit release tag or full commit without changing the default pin | Ubuntu, exact Bash 4.2.53, macOS Homebrew Bash, and standalone artifact jobs passed in [run 37652182510](https://github.com/basefoundry/base-bash-libs-demo/actions/runs/37652182510) | v2.2.0 first-party release validation pass; excluded from independent count |
+| Base Bash Demo | First-party isolated reference consumer | released [v0.1.2](https://github.com/basefoundry/base-bash-libs-demo/releases/tag/v0.1.2) at `ab4da09`; docs and vendor target the verified v2.2.0 bundle while v2.2.1 is the current upstream release | Commits the verified canonical v2.2.0 bundle, lock, checksum manifest, provenance, and SPDX SBOM; candidate checks use an explicit release tag or full commit without changing the default pin | Ubuntu, exact Bash 4.2.53, macOS Homebrew Bash, and standalone artifact jobs passed for the v0.1.2 release preparation | v2.2.0 first-party release validation pass; excluded from independent count |
 | BankBuddy | Adjacent repository; no direct `base-bash-libs` reference | `e32561c` | None | Repository validation: **312 passed** | Excluded from the consumer count |
 | BanyanLabs | Adjacent repository; no direct `base-bash-libs` reference | `15ef6cd` | None | Repository baseline present | Excluded from the consumer count |
 | Homebrew | First-party package-manager consumer | merged [#85](https://github.com/basefoundry/homebrew-base/pull/85), bottle release `base-v1.8.0` | `base-bash-libs` v2.0.0 bundle and Base v1.8.0 archive are hash-pinned; both macOS bottles published | Both bottle builds and v2 API smoke tests passed; installed GA upgrade, formula tests, and rollback to Base 1.7.0/base-bash-libs 1.4.0 passed | GA formula, bottles, upgrade, and rollback pass |

docs/v2/quickstart.md

@@ -78,3 +78,12 @@ their caller-relative meaning.
 
 The complete process is also available offline in the
 [`tests/consumer-kit`](../../tests/consumer-kit/README.md) fixture.
+
+## 4. See a complete application
+
+For a consumer that applies these contracts to a small offline application,
+continue with [Beacon's pinned five-minute tutorial](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/five-minute-tutorial.md).
+Then read [why Base Bash](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/why-base-bash-libs.md)
+and the [adoption decision guide](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/should-i-use-base-bash-libs.md).
+This is a first-party reference consumer and compatibility canary, not an
+independent-adoption claim.

tests/docs-contract.sh

@@ -80,6 +80,28 @@ grep -F 'v2/quickstart.md' docs/README.md > /dev/null || {
     printf 'Documentation link is missing: v2/quickstart.md\n' >&2
     exit 1
 }
+for demo_contract_url in \
+    'https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/README.md' \
+    'https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/five-minute-tutorial.md' \
+    'https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/why-base-bash-libs.md' \
+    'https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/should-i-use-base-bash-libs.md'; do
+    grep -R -F "$demo_contract_url" README.md docs/README.md docs/v2/quickstart.md > /dev/null || {
+        printf 'Pinned Beacon learning-path link is missing: %s\n' "$demo_contract_url" >&2
+        exit 1
+    }
+done
+grep -F 'five-minute, offline Beacon application' README.md > /dev/null || {
+    printf 'README must describe Beacon as a runnable learning path.\n' >&2
+    exit 1
+}
+grep -F 'See a complete application' docs/v2/quickstart.md > /dev/null || {
+    printf 'The v2 quickstart must link to the complete Beacon application.\n' >&2
+    exit 1
+}
+grep -F 'released [v0.1.2]' docs/consumer-validation-status.md > /dev/null || {
+    printf 'Consumer validation status must reference the current Beacon release.\n' >&2
+    exit 1
+}
 grep -F 'v2/architecture.md' docs/README.md > /dev/null || {
     printf 'Documentation link is missing: v2/architecture.md\n' >&2
     exit 1