fix(ci): ensure complete TagLib source extraction and add verification

Found and fixed cmake error using act local testing:
- CMake Error: "/tmp/taglib-2.0.2" does not contain CMakeLists.txt

Root cause: The source extraction was incomplete, leaving the directory
structure but missing critical files like CMakeLists.txt.

Fix:
- Always re-extract source (remove cached incomplete extraction)
- Add verification step to check CMakeLists.txt exists
- Fail fast with clear error message if extraction incomplete

Update act-guide.md with debugging example showing how act revealed
the hidden cmake error that was invisible in CI logs.

Tested: scripts/build-taglib.sh --force (Success: libtag.a built)

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

Author: pythoninthegrass

docs/act-guide.md

@@ -6,13 +6,32 @@
 # Run lint checks (fastest, fully compatible)
 act -W .github/workflows/test-local.yml -j lint
 
+# Debug build issues (runs natively on your machine)
+act -j build -W .github/workflows/test.yml 2>&1 | tee /tmp/act-build.log
+
 # List all available workflows and jobs
 act -l
 
 # Run specific workflow
 act -W .github/workflows/test-local.yml
 ```
 
+## Debugging with act
+
+act is invaluable for debugging CI failures:
+
+1. **Reproduce errors locally** - Run the exact same steps as CI
+2. **Iterate quickly** - No need to push/wait for CI
+3. **See full output** - All logs captured (even what's hidden in CI)
+4. **Native execution** - Self-hosted runners run on your machine with all your tools
+
+**Example**: We used act to find the cmake error in `build-taglib.sh`:
+```bash
+act -j build 2>&1 | tee /tmp/act-build.log
+grep -i "cmake error" /tmp/act-build.log
+# Found: CMake Error: The source directory "/tmp/taglib-2.0.2" does not appear to contain CMakeLists.txt.
+```
+
 ## Why test-local.yml?
 
 The `test-local.yml` workflow is designed for act compatibility:

scripts/build-taglib.sh

@@ -60,9 +60,16 @@ if [[ ! -f "${SOURCE_TAR}" ]]; then
         -o "${SOURCE_TAR}"
 fi
 
-if [[ ! -d "${SOURCE_DIR}" ]]; then
-    echo "Extracting source..."
-    tar xzf "${SOURCE_TAR}" -C /tmp
+# Always re-extract to ensure complete source tree
+echo "Extracting source..."
+rm -rf "${SOURCE_DIR}"
+tar xzf "${SOURCE_TAR}" -C /tmp
+
+# Verify CMakeLists.txt exists
+if [[ ! -f "${SOURCE_DIR}/CMakeLists.txt" ]]; then
+    echo "ERROR: CMakeLists.txt not found after extraction" >&2
+    echo "Expected at: ${SOURCE_DIR}/CMakeLists.txt" >&2
+    exit 1
 fi
 
 # Clean previous build