diff --git a/CLAUDE.md b/CLAUDE.md
index 1a02254..a29a577 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,6 +20,18 @@ Files are NEVER streamed through uwsgi. The server only generates presigned URLs
 - **Uploads**: presigned `post` → client uploads directly to Spaces
 - **Thumbnails**: public CDN URLs with `?ts=` cache busting
 
+### Karaoke Pipeline (lib/karaoke.py)
+
+Disk-backed vocal isolation pipeline. Downloads media from S3, builds a JSON
+request on disk with streaming base64 encoding, POSTs to unsandbox API, streams
+response to disk, decodes artifacts one at a time and uploads to S3.
+
+- **Concurrency**: `ThreadPoolExecutor` sized to account's unsandbox concurrency limit
+- **Memory**: ~64KB per worker on the request side (disk-backed, not in-memory)
+- **Upstream limit**: 3.698GB / 3,698,742,051 bytes per file (unsandbox `@max_upload_bytes`)
+- **Retries**: 3 attempts with exponential backoff (5s, 10s)
+- **Callers**: `views/product.py`, `views/shop.py` (backfill), `scripts/backfill_karaoke.py`
+
 ## Project Setup
 
 This project uses a Makefile for most development operations. Use `make` commands instead of running tools directly.