[README-001] Product-led README, demo media, and evidence-backed adoption path

[mrnicholasbcarter-code]

User story

As a new GitHub visitor, I need a trustworthy, welcoming README that explains Verdict Core in under one minute, proves the core promise with a credential-free demo, and gives clear next steps for users, contributors, and integrators.

Problem

Verdict Core's product vision is strong, but README quality directly controls adoption. The README must explain the control-plane problem to non-specialists without overselling unfinished integrations, and must connect claims to reproducible evidence.

Audit findings (2026-08-02)

• Verdict Core is the authoritative deterministic decision/enforcement plane.
• Core already has TaskSpec/routing, eligibility/capability checks, availability, evidence receipts, lifecycle/gateway adapters, memory/context integrations, CLI/API/docs, and extensive tests.
• The ecosystem is incomplete: universal ExecutionEnvelope, runtime enforcement closure, provider conformance, verification/evidence closure, and cross-repository compatibility remain tracked work.
• verdict-node is an edge adapter; risk/strategy/backtest are providers; cockpit is a control/observability UI; ecosystem is governance.
• Existing Core issues [VER-001] Versioned TaskSpec intake contract #218–[LAUNCH-002] Performance reliability and chaos baselines #239 cover the primary architecture backlog; Node Implement OmniRoute runtime availability and eligibility adapter #30/Build structured intake planner and adaptive workflow selector #31 and ecosystem chore(deps): bump actions/upload-artifact from 4 to 7 #6/P0: Make Ruflo/RuVector intelligence mandatory and bounded #7/P0: Implement transparent OpenAI-compatible proxy and streaming #8/P0: Reconcile OmniRoute discovery, availability, and filtered dispatch #9/P2: Add evidence-backed suggestion service from validated outcomes #11/P0: Reconcile OmniRoute discovery, availability, and filtered dispatch (#9) #12 cover newly identified cross-repo gaps.
• Existing README material contains strong concepts and a deterministic quickstart, but public claims must remain evidence-backed and status-labeled.

Target README

The README should make a first-time reader answer these questions quickly:

1. What problem does Verdict solve?
2. Who needs it?
3. What happens in the 30-second demo?
4. What is guaranteed now versus planned?
5. How do I install, try, integrate, contribute, or report a vulnerability?

Design direction

Use a product-led structure inspired by high-performing open-source repositories without copying them:

1. Hero: one-sentence value proposition, concise badges, demo links.
2. Plain-language problem/solution: explain governance before model selection.
3. 30-second credential-free quickstart with expected output.
4. Short visual: architecture diagram plus linked GIF/MP4/WebM demo.
5. “What is real today” table with evidence links and explicit maturity labels.
6. Core concepts: eligibility-before-ranking, immutable envelope, enforcement, verification, evidence, governed learning.
7. Ecosystem/adapters table distinguishing Core authority from Ruflo/RuVector/OmniRoute/providers.
8. Install paths: local/offline first, optional live providers second.
9. CLI/API examples for dry-run, explain, inspect, and evidence.
10. Security/trust section: fail-closed behavior, consented probes, privacy, supply-chain checks, vulnerability reporting.
11. Roadmap and architecture links.
12. Contributing, support, license, and star/follow call to action.

Media requirements

• Add one repository-owned or stable externally hosted architecture image with descriptive alt text.
• Add a 30-second demo recording showing install/quickstart, an allowed decision, a denied decision, and evidence/explanation output.
• Prefer a compressed GIF/WebM/MP4 with a static fallback; do not embed unstable local URLs.
• Add captions/transcript or equivalent text so the demo is accessible and reviewable without media playback.

Acceptance criteria

• A nontechnical reader can state the problem and value after the first 30 seconds of reading.
• README starts with a clear product sentence and working CI/security/Python/license badges; badges never imply unsupported maturity.
• Credential-free quickstart works from a clean checkout and expected output is checked in or generated deterministically.
• README includes a visible demo image/link and 30-second clip link with alt text/transcript.
• Architecture diagram clearly separates Core authority, adapters/providers, runtime, and UI.
• “Implemented / In progress / Planned” table links each claim to code, test, ADR, issue, or proof matrix.
• No unsupported claims such as production readiness, universal provider coverage, or guaranteed model counts remain.
• Install commands are tested on supported Python/Node versions and do not require credentials for the first demo.
• At least one beginner path and one integrator path are complete, copy-pasteable, and tested.
• Security, contributing, support, license, code of conduct, versioning, and issue links work.
• All internal links and code commands are validated in CI.
• README remains readable on GitHub mobile width; headings, tables, and code blocks are accessible.
• README claims use the claims ledger/proof matrix and state evidence limitations.

Testing and validation

• Clean-checkout quickstart test with no network and no API keys.
• Link checker for relative files, workflows, issue links, media, and anchors.
• Markdown lint and repository formatting checks.
• Shell command smoke test for every documented command.
• Screenshot/recording review at desktop and narrow viewport.
• Security/PII scan for media metadata, URLs, logs, and copied output.
• Adversarial review: attempt to find misleading claims, hidden credentials, broken first-run steps, confusing terminology, and evidence gaps.

Non-functional requirements

• First meaningful explanation within 120 words.
• Demo path under 30 seconds on a warm local environment and under 2 minutes from checkout.
• No required external account for the first successful demo.
• No secrets, private URLs, raw prompts, or personal data.
• Keep the README focused; move exhaustive API detail into linked docs.

Dependencies and references

• Core [VER-001] Versioned TaskSpec intake contract #218–[LAUNCH-002] Performance reliability and chaos baselines #239, especially [VER-001] Versioned TaskSpec intake contract #218–[VER-004] Provider adapter protocols and conformance harness #221, [VER-008] Native runtime enforcement kernel #225–[MEM-001] Memory governance, redaction, and verified-write gate #229, [DX-001] CLI explain, init, local defaults, and integration harness #237–[LAUNCH-002] Performance reliability and chaos baselines #239.
• Node Implement OmniRoute runtime availability and eligibility adapter #30/Build structured intake planner and adaptive workflow selector #31.
• Ecosystem Epic: Zero-Allocation Route Heuristics (Python) #1–chore(deps): bump actions/setup-python from 5 to 6 #3, chore(deps): bump actions/upload-artifact from 4 to 7 #6–P0: Reconcile OmniRoute discovery, availability, and filtered dispatch #9, P2: Add evidence-backed suggestion service from validated outcomes #11/P0: Reconcile OmniRoute discovery, availability, and filtered dispatch (#9) #12.
• CURRENT_STATE_AUDIT.md, ARCHITECTURE_GAP_ANALYSIS.md, IMPLEMENTATION_LIFT_ANALYSIS.md, ROADMAP.md in verdict-ecosystem.
• Related repositories: verdict-node, verdict-risk, verdict-strategy, verdict-backtest, verdict-cockpit, verdict-ecosystem, Ruflo, RuVector, OmniRoute.

Definition of done

README merged with media/transcript, clean-checkout demo verified, all links/commands checked, claims mapped to evidence, adversarial review resolved, and issue/roadmap links updated.

[mrnicholasbcarter-code]

User story

As a new GitHub visitor, I need a trustworthy, welcoming README that explains Verdict Core in under one minute, proves the core promise with a credential-free demo, and gives clear next steps for users, contributors, and integrators.

Problem

Verdict Core's product vision is strong, but README quality directly controls adoption. The README must explain the control-plane problem to non-specialists without overselling unfinished integrations, and must connect claims to reproducible evidence.

Audit findings (2026-08-02)

• Verdict Core is the authoritative deterministic decision/enforcement plane.
• Core already has TaskSpec/routing, eligibility/capability checks, availability, evidence receipts, lifecycle/gateway adapters, memory/context integrations, CLI/API/docs, and extensive tests.
• The ecosystem is incomplete: universal ExecutionEnvelope, runtime enforcement closure, provider conformance, verification/evidence closure, and cross-repository compatibility remain tracked work.
• verdict-node is an edge adapter; risk/strategy/backtest are providers; cockpit is a control/observability UI; ecosystem is governance.
• Existing Core issues [VER-001] Versioned TaskSpec intake contract #218–[LAUNCH-002] Performance reliability and chaos baselines #239 cover the primary architecture backlog; Node Implement OmniRoute runtime availability and eligibility adapter #30/Build structured intake planner and adaptive workflow selector #31 and ecosystem chore(deps): bump actions/upload-artifact from 4 to 7 #6/P0: Make Ruflo/RuVector intelligence mandatory and bounded #7/P0: Implement transparent OpenAI-compatible proxy and streaming #8/P0: Reconcile OmniRoute discovery, availability, and filtered dispatch #9/P2: Add evidence-backed suggestion service from validated outcomes #11/P0: Reconcile OmniRoute discovery, availability, and filtered dispatch (#9) #12 cover newly identified cross-repo gaps.
• Existing README material contains strong concepts and a deterministic quickstart, but public claims must remain evidence-backed and status-labeled.

Target README

The README should make a first-time reader answer these questions quickly:

1. What problem does Verdict solve?
2. Who needs it?
3. What happens in the 30-second demo?
4. What is guaranteed now versus planned?
5. How do I install, try, integrate, contribute, or report a vulnerability?

Design direction

Use a product-led structure inspired by high-performing open-source repositories without copying them:

1. Hero: one-sentence value proposition, concise badges, demo links.
2. Plain-language problem/solution: explain governance before model selection.
3. 30-second credential-free quickstart with expected output.
4. Short visual: architecture diagram plus linked GIF/MP4/WebM demo.
5. “What is real today” table with evidence links and explicit maturity labels.
6. Core concepts: eligibility-before-ranking, immutable envelope, enforcement, verification, evidence, governed learning.
7. Ecosystem/adapters table distinguishing Core authority from Ruflo/RuVector/OmniRoute/providers.
8. Install paths: local/offline first, optional live providers second.
9. CLI/API examples for dry-run, explain, inspect, and evidence.
10. Security/trust section: fail-closed behavior, consented probes, privacy, supply-chain checks, vulnerability reporting.
11. Roadmap and architecture links.
12. Contributing, support, license, and star/follow call to action.

Media requirements

• Add one repository-owned or stable externally hosted architecture image with descriptive alt text.
• Add a 30-second demo recording showing install/quickstart, an allowed decision, a denied decision, and evidence/explanation output.
• Prefer a compressed GIF/WebM/MP4 with a static fallback; do not embed unstable local URLs.
• Add captions/transcript or equivalent text so the demo is accessible and reviewable without media playback.

Acceptance criteria

• A nontechnical reader can state the problem and value after the first 30 seconds of reading.
• README starts with a clear product sentence and working CI/security/Python/license badges; badges never imply unsupported maturity.
• Credential-free quickstart works from a clean checkout and expected output is checked in or generated deterministically.
• README includes a visible demo image/link and 30-second clip link with alt text/transcript.
• Architecture diagram clearly separates Core authority, adapters/providers, runtime, and UI.
• “Implemented / In progress / Planned” table links each claim to code, test, ADR, issue, or proof matrix.
• No unsupported claims such as production readiness, universal provider coverage, or guaranteed model counts remain.
• Install commands are tested on supported Python/Node versions and do not require credentials for the first demo.
• At least one beginner path and one integrator path are complete, copy-pasteable, and tested.
• Security, contributing, support, license, code of conduct, versioning, and issue links work.
• All internal links and code commands are validated in CI.
• README remains readable on GitHub mobile width; headings, tables, and code blocks are accessible.
• README claims use the claims ledger/proof matrix and state evidence limitations.

Testing and validation

• Clean-checkout quickstart test with no network and no API keys.
• Link checker for relative files, workflows, issue links, media, and anchors.
• Markdown lint and repository formatting checks.
• Shell command smoke test for every documented command.
• Screenshot/recording review at desktop and narrow viewport.
• Security/PII scan for media metadata, URLs, logs, and copied output.
• Adversarial review: attempt to find misleading claims, hidden credentials, broken first-run steps, confusing terminology, and evidence gaps.

Non-functional requirements

• First meaningful explanation within 120 words.
• Demo path under 30 seconds on a warm local environment and under 2 minutes from checkout.
• No required external account for the first successful demo.
• No secrets, private URLs, raw prompts, or personal data.
• Keep the README focused; move exhaustive API detail into linked docs.

Dependencies and references

• Core [VER-001] Versioned TaskSpec intake contract #218–[LAUNCH-002] Performance reliability and chaos baselines #239, especially [VER-001] Versioned TaskSpec intake contract #218–[VER-004] Provider adapter protocols and conformance harness #221, [VER-008] Native runtime enforcement kernel #225–[MEM-001] Memory governance, redaction, and verified-write gate #229, [DX-001] CLI explain, init, local defaults, and integration harness #237–[LAUNCH-002] Performance reliability and chaos baselines #239.
• Node Implement OmniRoute runtime availability and eligibility adapter #30/Build structured intake planner and adaptive workflow selector #31.
• Ecosystem Epic: Zero-Allocation Route Heuristics (Python) #1–chore(deps): bump actions/setup-python from 5 to 6 #3, chore(deps): bump actions/upload-artifact from 4 to 7 #6–P0: Reconcile OmniRoute discovery, availability, and filtered dispatch #9, P2: Add evidence-backed suggestion service from validated outcomes #11/P0: Reconcile OmniRoute discovery, availability, and filtered dispatch (#9) #12.
• CURRENT_STATE_AUDIT.md, ARCHITECTURE_GAP_ANALYSIS.md, IMPLEMENTATION_LIFT_ANALYSIS.md, ROADMAP.md in verdict-ecosystem.
• Related repositories: verdict-node, verdict-risk, verdict-strategy, verdict-backtest, verdict-cockpit, verdict-ecosystem, Ruflo, RuVector, OmniRoute.

Definition of done

README merged with media/transcript, clean-checkout demo verified, all links/commands checked, claims mapped to evidence, adversarial review resolved, and issue/roadmap links updated.

[mrnicholasbcarter-code]

Adversarial review completed. Critical findings: canonical repo URL mismatch in installer/metadata, inaccurate TypeScript package names, Python version mismatch, unsupported OmniRoute wording, and overbroad security claims. README draft updated in worktree codex/readme-bespoke; implementation must resolve these before merge. Review also confirmed all relative links resolve.

[mrnicholasbcarter-code]

Product positioning clarification from project owner: Verdict exists to maximize the value of existing Claude Code Max, Codex Pro, 9router, and OmniRoute access. The primary user outcome is cost/usage-aware routing: classify task difficulty, risk, context, and tool needs; filter incapable/unsafe models; route routine work to the least expensive capable provider; reserve frontier models for genuinely difficult or sensitive work; escalate when needed; record the rationale and outcome. The product is not “always choose the cheapest model”; it is “choose the cheapest model that is good enough, while preserving premium capacity.” README draft now leads with this use case and explains it before governance terminology.

[mrnicholasbcarter-code]

Implemented and merged via PR #255: #255. Merge commit: 5898b2d. All required CI checks passed (build, Python 3.10–3.13 tests, lint, type-check, security, CodeQL, OSV, install smoke, example smoke, contract parity, benchmark). README updates are live on main.