docs: improve README formatting and clarity

README.md

@@ -29,11 +29,15 @@ Homebrew pulls in `ffmpeg` and `portaudio`, so `transcribe`, `stream`, and `agen
 
 ### pipx / uv
 
+With pipx:
+
 ```sh
-# pipx
 pipx install "git+https://github.com/AssemblyAI/cli.git"
+```
 
-# uv
+Or with uv:
+
+```sh
 uv tool install "git+https://github.com/AssemblyAI/cli.git"
 ```
 
@@ -72,43 +76,89 @@ Checked before the keyring, so nothing is written to disk — ideal for CI (set
 
 ### Basic usage
 
+Guided setup: sign in, first transcription, start building:
+
 ```sh
-# Guided setup: sign in, first transcription, start building
 assembly onboard
+```
+
+Transcribe the hosted sample:
 
-# Transcribe the hosted sample, then your own audio
+```sh
 assembly transcribe --sample
+```
+
+Then your own audio:
+
+```sh
 assembly transcribe call.mp3
+```
+
+Stream the microphone live (Ctrl-C to stop):
 
-# Stream the microphone live (Ctrl-C to stop)
+```sh
 assembly stream
+```
 
-# Talk to a voice agent
+Talk to a voice agent:
+
+```sh
 assembly agent
+```
+
+Scaffold a starter app:
 
-# Scaffold a starter app
+```sh
 assembly init
 ```
 
 ### Quick examples
 
+Just the text:
+
 ```sh
-# Just the text, or captions
 assembly transcribe call.mp3 -o text
+```
+
+Or captions:
+
+```sh
 assembly transcribe video.mp4 -o srt
+```
+
+Speaker labels + summary, as JSON:
 
-# Speaker labels + summary, as JSON
+```sh
 assembly transcribe call.mp3 --speaker-labels --summarization --json
+```
 
-# Batch: a whole directory or glob, resumable on re-run
+Batch: a whole directory or glob, resumable on re-run:
+
+```sh
 assembly transcribe ./recordings
+```
+
+Or pipe paths in:
+
+```sh
 find . -name "*.wav" | assembly transcribe --from-stdin
+```
 
-# Pipe audio in, pipe text out
+Pipe audio in, pipe text out:
+
+```sh
 ffmpeg -i talk.mp4 -f wav - | assembly transcribe -
+```
+
+Prompt the LLM Gateway over any text:
+
+```sh
 git log --oneline -30 | assembly llm "write release notes grouped by feature/fix"
+```
 
-# Print the equivalent Python SDK script instead of running
+Print the equivalent Python SDK script instead of running:
+
+```sh
 assembly transcribe --sample --speaker-labels --show-code
 ```
 
@@ -123,10 +173,22 @@ assembly transcribe --sample --speaker-labels --show-code
 
 This project uses [uv](https://docs.astral.sh/uv/):
 
+Create/refresh the venv:
+
+```sh
+uv sync
+```
+
+Run the CLI from the locked environment:
+
+```sh
+uv run assembly --help
+```
+
+Run the full gate CI runs:
+
 ```sh
-uv sync               # create/refresh the venv
-uv run assembly --help     # run the CLI from the locked environment
-./scripts/check.sh    # the full gate CI runs
+./scripts/check.sh
 ```
 
 See [AGENTS.md](AGENTS.md) for development conventions and architecture notes.