docs: add comprehensive VirtualBuddy TSS API documentation to CLAUDE.md

Documents the VirtualBuddy API integration including:
- API endpoint, board config, and response fields
- Rate limits (2 req/5 sec) and 12-hour server cache
- HTTP status codes and error handling
- Client-side rate limiting implementation (2.5-5.0s random delays)
- Deduplication priority (authoritative source for isSigned)
- Example JSON responses for signed and unsigned builds

Based on TSSBuddy.pdf API documentation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: leogdion

CLAUDE.md

@@ -154,6 +154,72 @@ Multiple sources provide overlapping data. The pipeline deduplicates using:
 
 See `.claude/implementation-patterns.md` for detailed deduplication logic and code examples.
 
+### VirtualBuddy TSS API Integration
+
+**Purpose**: VirtualBuddy provides real-time TSS (Tatsu Signing Status) verification for macOS restore images for virtual machines.
+
+**API Endpoint**:
+```
+GET https://tss.virtualbuddy.app/v1/status?apiKey=<key>&ipsw=<IPSW URL>
+```
+
+**Board Config**: Checks `VMA2MACOSAP` (macOS virtual machines)
+
+**Key Response Fields**:
+- `isSigned` (boolean) - true if Apple is signing the build, false otherwise
+- `uuid` - Request tracking ID for debugging
+- `version` - macOS version (e.g., "15.0")
+- `build` - Build number (e.g., "24A5327a")
+- `code` - Status code (0 = SUCCESS, 94 = not eligible)
+- `message` - Human-readable status message
+
+**HTTP Status Codes**:
+- `200` - Success (returned regardless of signing status)
+- `400` - Bad request (invalid IPSW URL)
+- `429` - Rate limit exceeded
+- `500` - Internal server error
+
+**Rate Limits & Caching**:
+- **Rate limit**: 2 requests per 5 seconds
+- **Server-side CDN cache**: 12 hours (to avoid Apple TSS rate limiting)
+- **Client-side implementation**: Random delays of 2.5-5.0 seconds between requests
+
+**Implementation Details**:
+- **File**: `Sources/BushelCloudKit/DataSources/VirtualBuddyFetcher.swift`
+- **Integration**: Enriches RestoreImageRecord with real-time signing status after other data sources
+- **Error handling**: HTTP 429 errors are logged; original record preserved on any error
+- **Progress tracking**: Shows "X/Y images checked" during sync
+- **Performance**: ~3-4 minutes for 50 images (acceptable for 8-16 hour sync schedules)
+
+**Deduplication Priority**:
+- VirtualBuddy is an **authoritative source** for `isSigned` status (along with MESU)
+- Takes precedence over other sources when merging duplicate records
+- See `DataSourcePipeline.swift:429-447` for merge logic
+
+**Example Response (Signed)**:
+```json
+{
+  "uuid": "67919BEC-F793-4544-A5E6-152EE435DCA6",
+  "version": "15.0",
+  "build": "24A5327a",
+  "code": 0,
+  "message": "SUCCESS",
+  "isSigned": true
+}
+```
+
+**Example Response (Unsigned)**:
+```json
+{
+  "uuid": "02A12F2F-CE0E-4FBF-8155-884B8D9FD5CB",
+  "version": "15.1",
+  "build": "24B5024e",
+  "code": 94,
+  "message": "This device isn't eligible for the requested build.",
+  "isSigned": false
+}
+```
+
 ### Logging
 
 The project uses structured logging with `BushelLogger` (wrapping `os.Logger`):