docs: link the reference consumer as a learning path from the docs index and quickstart #568

Goal

Make the maintained reference consumer discoverable as a learning path from the places a new user actually starts.

Background

base-bash-libs-demo is the only repository that shows a complete application built on the library, but upstream links to it from exactly one paragraph: README.md line 73, which describes it as "a downstream compatibility canary… regression evidence", a testing framing. docs/README.md and docs/v2/quickstart.md do not mention it (grep for "demo" matches only the demo directory the quickstart creates, line 40-42). docs/who-uses-base-bash.md and docs/consumer-validation-status.md list it as evidence, not as a tutorial. The demo's README sends users the other way (to the quickstart), so a reader following either repo never completes the loop.

Scope

• Add the demo to docs/README.md "Start here" and as the next step after docs/v2/quickstart.md: "see a complete application: Beacon".
• Reframe the README paragraph to lead with what a reader can learn and run (offline, five minutes), then note its canary role.
• Link to specific demo pages: the five-minute tutorial, "Why Base Bash?", and the adoption decision guide.
• Pin the links to demo tag v0.1.0 (or the current release) and extend tests/docs-contract.sh so they cannot rot.

Acceptance Criteria

• The demo is reachable in one click from the docs index and the quickstart.
• The README no longer describes the demo only as regression evidence.
• The docs contract fails if a demo link is broken or unpinned.

Validation

• ./tests/docs-contract.sh
• ./tests/validate.sh
• Demo repo: ./tests/docs-contracts.sh still passes

Non-Goals

• Do not claim the demo is independent adoption evidence.

Project Fields

• Status: Ready
• Priority: P2
• Area: Docs
• Initiative: Adoption Polish
• Size: S

Agent Assignment

• Assignee: @codeforester