Demo Readiness

One Command to Run

• The README quick-start runs top to bottom on a clean machine, in the order written
• One command starts everything — docker compose up, make run, ./gradlew bootRun, task demo, or the project's equivalent
• Every prerequisite is named with a version and an install link (Docker, JDK, Node, Xcode)
• The command to stop everything sits next to the command to start it

Prove It Clean

• Before shipping a demo, run the README steps from a fresh clone in a temp dir — never from the working checkout
• Stale screenshots, recorded outputs, and version numbers are removed or regenerated in the same PR
• A step that needs a manual click, a browser login, or a copied value is written out as that step, never assumed

Config Surface

• .env.example lists every variable per rules/no-secrets.md, with a working default where one exists
• Defaults work offline where possible — local containers before hosted services
• Cloud credentials (Confluent Cloud, a hosted model API, a SaaS key) are an optional path with its own section, never the only path
• A demo that requires a paid account says so in the first screen of the README

Reset State

• A documented command returns the demo to its starting state — topics, tables, caches, and containers recreated, not hand-cleaned
• Reset is idempotent per rules/file-hygiene.md Idempotency — safe to run twice, safe to run on a fresh clone
• Seed data is generated by a script in the repo, never checked in as a binary dump (rules/testing-standards.md Fixtures)

Scope

• Governs repositories whose audience is a talk, workshop, blog post, or live demo
• Every other repo follows the general rules only