diff --git a/tests/README.md b/crates/miroir-proxy/tests/README_integration.md
similarity index 89%
rename from tests/README.md
rename to crates/miroir-proxy/tests/README_integration.md
index 803f446..8067af7 100644
--- a/tests/README.md
+++ b/crates/miroir-proxy/tests/README_integration.md
@@ -21,19 +21,19 @@ docker compose -f examples/docker-compose-dev.yml ps
 Run all integration tests:
 
 ```bash
-cargo test --test integration -- --test-threads=1
+cargo test -p miroir-proxy --test docker_compose_integration -- --test-threads=1
 ```
 
 Run a specific test:
 
 ```bash
-cargo test --test integration test_document_round_trip -- --exact
+cargo test -p miroir-proxy --test docker_compose_integration test_document_round_trip -- --exact
 ```
 
 Run tests with output:
 
 ```bash
-cargo test --test integration -- --test-threads=1 --nocapture
+cargo test -p miroir-proxy --test docker_compose_integration -- --test-threads=1 --nocapture
 ```
 
 ## Test Coverage
@@ -59,7 +59,7 @@ The `test_node_failure_rf2` test requires the RF=2 docker-compose stack:
 docker compose -f examples/docker-compose-dev-rf2.yml up -d
 
 # Run the node failure test
-cargo test --test integration test_node_failure_rf2 -- --ignored
+cargo test -p miroir-proxy --test docker_compose_integration test_node_failure_rf2 -- --ignored
 
 # Clean up
 docker compose -f examples/docker-compose-dev-rf2.yml down -v
diff --git a/tests/integration.rs b/crates/miroir-proxy/tests/docker_compose_integration.rs
similarity index 98%
rename from tests/integration.rs
rename to crates/miroir-proxy/tests/docker_compose_integration.rs
index 6b5d46e..bbefa3e 100644
--- a/tests/integration.rs
+++ b/crates/miroir-proxy/tests/docker_compose_integration.rs
@@ -111,7 +111,7 @@ impl HttpClient {
 }
 
 /// Wait for a task to complete by polling the task endpoint
-async fn wait_for_task(client: &HttpClient, index_uid: &str, task_uid: u64, timeout_secs: u64) -> Result<serde_json::Value, String> {
+async fn wait_for_task(client: &HttpClient, _index_uid: &str, task_uid: u64, timeout_secs: u64) -> Result<serde_json::Value, String> {
     let start = std::time::Instant::now();
     let timeout = Duration::from_secs(timeout_secs);
 
@@ -136,12 +136,13 @@ async fn wait_for_task(client: &HttpClient, index_uid: &str, task_uid: u64, time
 
 /// Generate test documents with unique keywords for shard coverage testing
 fn generate_test_documents(count: usize) -> Vec<serde_json::Value> {
+    let colors = ["red", "green", "blue"];
     (0..count).map(|i| {
         json!({
             "id": i,
             "title": format!("Document {}", i),
             "keyword": format!("keyword_{}", i % 16), // 16 unique keywords for 16 shards
-            "color": ["red", "green", "blue"][i % 3], // For facet testing
+            "color": colors[i % 3], // For facet testing
             "score": i % 100,
             "shard_hint": format!("shard_{}", i % 16), // Help verify shard distribution
         })
@@ -317,10 +318,11 @@ async fn test_facet_aggregation() {
     wait_for_task(&client, "facet_test", task_uid, 30).await.unwrap();
 
     // Index exactly 100 documents with known color distribution
+    let colors = ["red", "green", "blue"];
     let docs: Vec<serde_json::Value> = (0..100).map(|i| {
         json!({
             "id": i,
-            "color": ["red", "green", "blue"][i % 3],
+            "color": colors[i % 3],
         })
     }).collect();
 
@@ -577,8 +579,6 @@ async fn test_health_check() {
 /// Test 8: Direct Meilisearch node access (for debugging)
 #[tokio::test]
 async fn test_direct_meilisearch_access() {
-    let client = HttpClient::new();
-
     // Access Meilisearch node 0 directly
     let client = reqwest::Client::builder()
         .timeout(Duration::from_secs(5))
diff --git a/examples/README.md b/examples/README.md
index 7e8905c..6bd2800 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -170,3 +170,30 @@ For production deployments on Kubernetes, use the [Miroir Helm chart](https://gi
 ## CI/CD
 
 The Docker Compose stack is exercised by CI smoke tests on every PR. See [k8s/argo-workflows/miroir-ci-docker-compose-smoke.yaml](../k8s/argo-workflows/miroir-ci-docker-compose-smoke.yaml) for the test workflow.
+
+## Integration Tests
+
+This Docker Compose setup doubles as the integration test harness. Comprehensive integration tests are located in `crates/miroir-proxy/tests/docker_compose_integration.rs` with documentation in `crates/miroir-proxy/tests/README_integration.md`.
+
+Run integration tests:
+
+```bash
+# Start the stack
+docker compose -f examples/docker-compose-dev.yml up -d
+
+# Run all integration tests
+cargo test -p miroir-proxy --test docker_compose_integration -- --test-threads=1
+
+# Clean up
+docker compose -f examples/docker-compose-dev.yml down -v
+```
+
+Integration test coverage includes:
+- Document round-trip (1000 documents)
+- Search coverage across all 16 shards
+- Facet aggregation
+- Offset/limit pagination
+- Settings broadcast
+- Task polling
+- Health checks
+- Node failure with RF=2 (requires `docker-compose-dev-rf2.yml`)