From 3dc0374f158a360b1399b2a540f56f0403b1b8e3 Mon Sep 17 00:00:00 2001
From: ab-10 <armins.bagrats@gmail.com>
Date: Sat, 24 Jan 2026 14:23:49 -0800
Subject: [PATCH] Add CI/CD install instructions

---
 README.md | 48 +++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 39 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index c7bf0bb..83f4ce4 100644
--- a/README.md
+++ b/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.