chore(integration): add testdata rotation target + document workflow

Surfaced via the rfc-5737-cleanup sweep: after the anonymisation pass
updated test-suite assertions to RFC-5737 IPs, the next
`make test-http-client` run failed against the stale local
tests/integration/testdata/ left over from a previous build (which
still carried the old 192.168.1.x state via the compose volume).

Two changes, in one commit so the doc references the target it
documents:

1. Makefile: new `test-http-client-rotate` target that renames any
   existing tests/integration/testdata/ to
   tests/integration/testdata_<timestamp>/. Non-destructive (mv, not
   rm), opt-in (no other target invokes it). Archives stay around
   for retrospective debugging — that directory is debug evidence,
   not disposable scratch.

2. CLAUDE.md: new "Integration tests" section under Build/test/run.
   Explains the docker-compose stack, the testdata mount, the
   per-machine-only nature (via tests/.gitignore), and the
   rotate-then-run pattern when fixtures or schemas have changed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -65,6 +65,33 @@ before `git push`. CI runs it on every PR; running it locally first
 saves a round-trip. `make check` covers `lint` is its own target —
 combine as needed.
 
+## Integration tests
+
+The `.http` integration tests under `tests/integration/http-client/`
+run via `make test-http-client`, which spins up the service plus
+support mocks (`spotify-mock`, `amazon-mock`) using
+`docker-compose.yml` + `docker-compose.ci.yml`, executes the suite
+through the JetBrains HTTP client image, then tears the stack down.
+Requires Docker.
+
+The compose CI override mounts `tests/integration/testdata/` into the
+service container as its persistent data dir. That directory is
+listed in `tests/.gitignore` — it's local developer state, not source.
+
+**Treat the testdata dir as debug evidence, not disposable scratch.**
+When a fixture or schema change makes the old state stale (e.g.
+post-anonymisation, the previous run's IPs no longer match the
+assertions), don't `rm -rf` it — archive it:
+
+```bash
+make test-http-client-rotate   # renames testdata/ → testdata_<timestamp>/
+make test-http-client          # fresh run on a clean slate
+```
+
+The rotate target is non-destructive (it moves, never deletes) and
+opt-in (no other target invokes it). Old archives stay around for
+retrospective diffing whenever something goes sideways.
+
 ## Project structure
 
 ```

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all build build-cli test test-coverage check fmt vet lint clean dev help screenshots build-stockholm-image prepare-stockholm
+.PHONY: all build build-cli test test-coverage test-http-client test-http-client-rotate check fmt vet lint clean dev help screenshots build-stockholm-image prepare-stockholm
 
 # Load .env if present (simple KEY=VALUE format, no shell quoting)
 -include .env
@@ -149,6 +149,20 @@ test-coverage:
 
 check: fmt vet test test-http-client
 
+# Archive any existing tests/integration/testdata/ to a timestamped sibling
+# so the next `make test-http-client` starts from a clean slate. Keeps the
+# old state around for retrospective debugging — never destructive.
+# Run BEFORE test-http-client when fixtures or schemas have changed and
+# stale state would otherwise be reused via the compose volume mount.
+test-http-client-rotate:
+	@if [ -d tests/integration/testdata ]; then \
+		archive=tests/integration/testdata_$$(date +%Y%m%d-%H%M%S); \
+		mv tests/integration/testdata "$$archive"; \
+		echo "Archived existing testdata to $$archive"; \
+	else \
+		echo "No tests/integration/testdata/ to archive — already fresh."; \
+	fi
+
 test-http-client:
 	@echo "Starting services with docker compose..."
 	@docker compose -f docker-compose.yml -f docker-compose.ci.yml up -d --build
@@ -448,6 +462,8 @@ help:
 	@echo "  build-linux-armv7 - Build for Linux ARMv7 (kernel 3.14+ compatible, CGO_ENABLED=0)"
 	@echo "  test          - Run tests"
 	@echo "  test-coverage - Run tests with coverage report"
+	@echo "  test-http-client         - Run .http integration tests via Docker Compose"
+	@echo "  test-http-client-rotate  - Archive tests/integration/testdata/ before a fresh run (non-destructive)"
 	@echo "  check         - Run fmt, vet, and tests"
 	@echo "  fmt           - Format code"
 	@echo "  vet           - Run go vet"