From db49dff32b154ec5771aa6f99abf67a5d79a42af Mon Sep 17 00:00:00 2001
From: Ashay <ashay.singh@sadhguru.org>
Date: Mon, 10 Aug 2026 09:47:10 +0530
Subject: [PATCH] docs: add copy-paste Quickstart with install and expected
 output

First-run path: install (PyPI or editable), `voiceeval check` on the
shipped misheard fixture, and the real FAIL/PASS output blocks.

Fixes #1
---
 README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 56 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 6ad30b1..94a752d 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,59 @@ FAIL refund-misheard-fifty (7s call)
          Took consequential action (refund) without ever confirming.
 ```
 
+## Quickstart
+
+Install, run the smallest useful command, confirm the output.
+
+**From PyPI** ([voiceeval-cli](https://pypi.org/project/voiceeval-cli/)):
+
+```bash
+pip install voiceeval-cli
+```
+
+**From a clone** (dev):
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Minimal command (uses the shipped fixture; no API keys, no network):
+
+```bash
+voiceeval check fixtures/misheard_call.json
+```
+
+Expected output:
+
+```
+FAIL refund-misheard-fifty (7s call)
+  high   misheard_number turn 1
+         STT heard ['fifty'] but caller said ['fifteen']. A wrong number the
+agent acts on is the most expensive failure in voice.
+  high   no_confirmation turn 2
+         Took consequential action (refund) without ever confirming. If the STT
+misheard, this already happened.
+
+0/1 calls passed
+```
+
+A clean call passes with no findings:
+
+```bash
+voiceeval check fixtures/good_call.json
+```
+
+```
+PASS refund-happy-path (15s call)
+  no findings
+
+1/1 calls passed
+```
+
+The distribution name on PyPI is `voiceeval-cli` (the bare name is taken); the
+import path and the CLI command are both `voiceeval`.
+
 ## The problem
 
 Read that call's transcript and it is flawless. The caller asked for fifty dollars, the agent
@@ -103,25 +156,16 @@ scripted test calls: in production this failure is silent, and no tool can fix t
 
 ## Install
 
-**PyPI:** https://pypi.org/project/voiceeval-cli/
-
-```bash
-pip install voiceeval-cli
-voiceeval check fixtures/*.json
-```
+See [Quickstart](#quickstart) for copy-paste install and first command.
 
-The distribution is `voiceeval-cli` (the bare name is taken on PyPI by an unrelated
-project); the import path and the command are both `voiceeval`.
-
-From a clone, for development:
+Only dependency is `rich`. `[stt]` adds `groq` if you are starting from audio.
+Development extras:
 
 ```bash
 pip install -e ".[dev]"
 pytest -q                                  # 18 tests
 ```
 
-Only dependency is `rich`. `[stt]` adds `groq` if you are starting from audio.
-
 ## Design notes
 
 **Severity is conservative and there is a test for it.** `test_a_clean_call_passes_with_no_findings`