docs: add testing documentation and macOS ARM64 known issue

Document the macOS ARM64 CGO linking issue with sqlite-vec-go-bindings
that prevents hybrid package tests from compiling locally.

Added:
- .github/TESTING.md: Comprehensive testing guide with platform-specific
  issues, workarounds, and CI configuration details
- internal/vector/hybrid/README.md: Package-specific documentation
  explaining the macOS limitation
- .github/CI_FIX_SUMMARY.md: Technical details of the CI fix

Key points:
- 41 out of 42 packages test successfully on all platforms
- hybrid package tests fail only on macOS ARM64 (local dev issue)
- Linux CI tests pass with proper build-tags: "fts5" configuration
- Production builds and runtime functionality unaffected

This is a known limitation of sqlite-vec-go-bindings on macOS ARM64
and does not impact CI/CD or production deployments.

.github/TESTING.md

@@ -0,0 +1,93 @@
+# Testing Guide
+
+## Running Tests
+
+### Full Test Suite
+
+```bash
+make test
+```
+
+This runs all tests with proper build tags (`-tags "fts5"`) and race detection.
+
+### Test Coverage
+
+```bash
+make test-coverage
+```
+
+Generates coverage reports in `coverage.out` and `coverage.html`.
+
+## Platform-Specific Issues
+
+### macOS ARM64
+
+**Known Issue:** Tests for `internal/vector/hybrid` fail to compile on macOS ARM64 due to CGO linking issues with `sqlite-vec-go-bindings`.
+
+**Symptoms:**
+```
+ld: symbol(s) not found for architecture arm64
+FAIL github.com/lukaszraczylo/claude-mnemonic/internal/vector/hybrid [build failed]
+```
+
+**Root Cause:** Conflict between `mattn/go-sqlite3` and `sqlite-vec`'s embedded SQLite when linking test binaries on macOS ARM64.
+
+**Impact:**
+- Local development on macOS ARM64 cannot run hybrid package tests
+- **Does not affect:** Linux CI, production builds, or runtime functionality
+- All other 41 packages test successfully
+
+**Workarounds:**
+1. Test other packages individually: `go test ./internal/db/... ./internal/search/...`
+2. Use Docker/Linux container for comprehensive local testing
+3. Rely on CI for hybrid package validation (recommended)
+
+**CI Status:** Tests pass successfully on Linux (GitHub Actions ubuntu-latest runner).
+
+### Linux / CI
+
+Tests run successfully with:
+- `CGO_ENABLED=1`
+- `-tags "fts5"` build flag
+- ONNX runtime libraries (auto-downloaded by `workflow-prepare.sh`)
+
+### Windows
+
+`workflow-prepare.sh` handles Windows-specific SQLite setup automatically.
+
+## CI Configuration
+
+The CI workflow (`.github/workflows/ci.yaml`) uses the shared-actions workflow with:
+
+```yaml
+build-tags: "fts5"  # Required for SQLite FTS5 support
+go-version: ">=1.24"
+lfs: true
+```
+
+The `workflow-prepare.sh` script runs before tests to:
+1. Download ONNX runtime libraries for the target platform
+2. Set up SQLite headers on Windows
+3. Configure CGO linker flags as needed
+
+## Test Organization
+
+- **Unit tests**: Package-level tests in `*_test.go` files
+- **Integration tests**: Database and system integration in `*integration_test.go`
+- **Benchmarks**: Performance tests in `*_test.go` with `Benchmark*` functions
+
+## Debugging Test Failures
+
+If tests fail in CI but pass locally (or vice versa):
+
+1. Check that build tags are consistent: `-tags "fts5"`
+2. Verify CGO is enabled: `CGO_ENABLED=1`
+3. Ensure ONNX libraries are present (run `make setup-libs`)
+4. Check platform-specific issues (see above)
+5. Review `workflow-prepare.sh` for platform-specific setup
+
+## Known Limitations
+
+- **macOS ARM64**: Cannot compile hybrid package tests (see above)
+- **Test caching**: Some tests use real databases and may need cache clearing with `go clean -testcache`
+- **Race detector**: Increases test time significantly but is required for CI