Add CI/CD install instructions

README.md

@@ -103,26 +103,56 @@ Run tests in CI with `RECORD_MODE=none` to replay from cached cassettes (no API
 ```yaml
 # .github/workflows/test.yml
 name: Tests
-on: [push, pull_request]
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
 
 jobs:
   test:
     runs-on: ubuntu-latest
+
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.12'
-      - name: Install tmux
-        run: sudo apt-get install -y tmux
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
       - name: Install dependencies
-        run: pip install -e ".[dev]"
-      - name: Run tests
-        run: RECORD_MODE=none pytest
+        run: uv sync
+
+      - name: Run tests (replay mode)
+        run: uv run pytest tests/ -v -s
+        env:
+          RECORD_MODE: none
 ```
 
+**Key points:**
+- `RECORD_MODE: none` ensures tests replay from cassettes and fail if any recording is missing
+- `-v -s` flags provide verbose output for easier debugging in CI logs
+- No `ANTHROPIC_API_KEY` needed in replay mode—cassettes contain all recorded responses
+
 Commit your `.cassettes/` directory to version control so CI can replay recordings.
 
+## Troubleshooting
+
+**"ANTHROPIC_API_KEY environment variable required"**
+- You're running in record mode without an API key. Either set `ANTHROPIC_API_KEY` or use `RECORD_MODE=none` to replay from existing cassettes.
+
+**"Cache miss in replay mode"**
+- A test is making an LLM call that wasn't recorded. Run locally with `RECORD_MODE=once` (or `all`) to record the missing interaction, then commit the updated cassette.
+
+**Cassette not found**
+- Ensure `.cassettes/` is committed to version control and not in `.gitignore`.
+
 ## Contributing
 
 Issues and PRs welcome.