docs: Deduplicate validate-check helper

Keep a single Makefile validate-check target that prints the full
/metrics dump, highlights hit/miss fields, and curls /lancache-heartbeat.
Drop the duplicate README troubleshooting item and align the validation
chapter plus validate-config.yaml comments with that behavior.

Link: #29

Makefile

@@ -62,15 +62,7 @@ validate run-validation: build clean-disk ## Start steamcache2 on :80 with small
 	fi; \
 	exec "$$BINARY" --config docs/examples/validate-config.yaml --log-level info
 
-validate-check: ## Print hit/miss fields from http://localhost/metrics (default listen_address :80)
-	@echo "=== steamcache2 cache check (http://localhost/metrics) ==="
-	@curl -sS --fail --max-time 5 http://localhost/metrics | grep -E '^(total_requests|cache_hits|cache_misses|hit_rate|memory_cache_hits|disk_cache_hits|errors) ' || { \
-		echo "ERROR: could not read hit/miss metrics from http://localhost/metrics"; \
-		echo "Is steamcache2 running on the default listen address (:80)?"; \
-		exit 1; \
-	}
-
-validate-check: ## Curl local /metrics (hit/miss) and /lancache-heartbeat (default :80)
+validate-check: ## Curl local /metrics (full dump + hit/miss fields) and /lancache-heartbeat (default :80)
 	@echo "=== http://localhost/metrics ==="
 	@metrics=$$(curl -sf --max-time 5 http://localhost/metrics) || { \
 		echo "ERROR: could not fetch http://localhost/metrics"; \
@@ -82,9 +74,15 @@ validate-check: ## Curl local /metrics (hit/miss) and /lancache-heartbeat (defau
 	echo "=== hit/miss fields ==="; \
 	printf '%s\n' "$$metrics" | grep -E '^(total_requests|cache_hits|cache_misses|hit_rate|memory_cache_hits|disk_cache_hits|errors) ' || true; \
 	echo ""; \
-	echo "=== http://localhost/lancache-heartbeat (expect 204 + X-LanCache-Processed-By: SteamCache2) ==="; \
-	curl -sD - -o /dev/null --max-time 5 http://localhost/lancache-heartbeat || { \
+	echo "=== http://localhost/lancache-heartbeat (GET; expect 204 + X-LanCache-Processed-By: SteamCache2) ==="; \
+	hb=$$(curl -sD - -o /dev/null --max-time 5 http://localhost/lancache-heartbeat) || { \
 		echo "ERROR: could not fetch http://localhost/lancache-heartbeat"; \
+		echo "Is steamcache2 running on the default listen address :80?"; \
+		exit 1; \
+	}; \
+	printf '%s\n' "$$hb"; \
+	echo "$$hb" | grep -q '204' && echo "$$hb" | grep -qi 'X-LanCache-Processed-By' || { \
+		echo "ERROR: expected HTTP 204 and X-LanCache-Processed-By on /lancache-heartbeat"; \
 		exit 1; \
 	}
 
@@ -135,7 +133,7 @@ help: ## Show this help message
 	@echo "  clean-disk         Remove disk cache"
 	@echo "  bench              Run low-level VFS microbenchmarks"
 	@echo "  validate / run-validation  Start server on :80 (builds, auto-setcaps fresh binary, then runs as normal user, cleans disk cache first)"
-	@echo "  validate-check     Print hit/miss fields from http://localhost/metrics (default listen :80)"
+	@echo "  validate-check     Curl local /metrics (full dump + hit/miss fields) and /lancache-heartbeat (default :80)"
 	@echo "  setcap               Explicitly set cap on current build (for port 80 use outside validate)"
 	@echo "  validate-kill      Kill leftover steamcache2 processes (safer)"
-	@echo "  prefill            Download latest SteamPrefill into bin/steam-prefill/SteamPrefill (gitignored)"
+	@echo "  prefill            Download latest SteamPrefill into bin/steam-prefill/SteamPrefill (gitignored)"

README.md

@@ -59,11 +59,12 @@ After steamcache2 is running (default `listen_address: :80`) and has seen a litt
 
 ```bash
 make validate-check
-# or:
+# or, manually:
 curl -s http://localhost/metrics
+curl -s -i http://localhost/lancache-heartbeat
 ```
 
-Read these fields:
+`make validate-check` prints the full `/metrics` dump, highlights hit/miss fields, and curls `/lancache-heartbeat`. Read these fields:
 
 | Field | Meaning |
 | --- | --- |
@@ -128,12 +129,13 @@ When the server is running, point your external SteamPrefill (or other load gene
 ./SteamPrefill benchmark run ...
 ```
 
-When finished, you can get a quick metrics summary with:
+When finished, you can get a quick metrics + heartbeat report with:
 
 ```bash
 make validate-check
-# or:
+# or, manually:
 curl -s http://localhost/metrics
+curl -s -i http://localhost/lancache-heartbeat
 ```
 
 See [Quick check: is it caching?](#quick-check-is-it-caching) for which fields to read. This is the recommended simple workflow. No automatic downloading or running of external tools.
@@ -144,16 +146,17 @@ After a benchmark run you can ask for a quick report:
 
 ```bash
 make validate-check
-# or manually:
+# or, manually:
 curl -s http://localhost/metrics
+curl -s -i http://localhost/lancache-heartbeat
 ```
 
-Look for:
+`make validate-check` prints the full `/metrics` dump, highlights hit/miss fields, and curls `/lancache-heartbeat`. Look for:
 - High cache hit rate after the warmup pass (`cache_hits`, `hit_rate`, plus `memory_cache_hits` / `disk_cache_hits`)
 - Non-zero `coalesced` and `disk` activity
 - Zero unexpected `errors`
 
-Heartbeat is the same as the operator check: `curl -s -i http://localhost/lancache-heartbeat` (HTTP 204, `X-LanCache-Processed-By: SteamCache2`).
+Heartbeat should be HTTP 204 with `X-LanCache-Processed-By: SteamCache2`. Use GET (`curl -i`), not HEAD (`curl -I`).
 
 #### The Validation Config
 
@@ -409,12 +412,7 @@ make
    - Adjust the disk cache size to match available storage
 
 6. **Not sure if it is caching**
-   - Do not start with the full SteamPrefill chapter. Use [Quick check: is it caching?](#quick-check-is-it-caching): `make validate-check` or `curl -s http://localhost/metrics`
-   - `cache_misses` on the first request is expected; a repeat of the same object should increment `cache_hits`
-   - `curl -si http://localhost/lancache-heartbeat` should return 204 and `X-LanCache-Processed-By: SteamCache2`
-
-6. **Not sure if it is caching**
-   - See [Quick check: is it caching?](#quick-check-is-it-caching): `make validate-check` or `curl -s http://localhost/metrics`
+   - Do not start with the full SteamPrefill chapter. Use [Quick check: is it caching?](#quick-check-is-it-caching): `make validate-check` (full `/metrics`, hit/miss fields, and `/lancache-heartbeat`)
    - A first pass is mostly `cache_misses`; repeating the same content should raise `cache_hits` / `hit_rate`
    - Confirm the process is up with `curl -s -i http://localhost/lancache-heartbeat` (GET, not HEAD)
 

docs/examples/validate-config.yaml

@@ -27,9 +27,10 @@
 #   SteamPrefill benchmark run -c 20 ...
 #
 # After the benchmark run, inspect with:
-#   make validate-check
-#   # or: curl -s http://localhost/metrics
-# Heartbeat (process up): curl -s -i http://localhost/lancache-heartbeat
+#   make validate-check   # full /metrics + hit/miss fields + /lancache-heartbeat
+#   # or, manually:
+#   curl -s http://localhost/metrics
+#   curl -s -i http://localhost/lancache-heartbeat   # GET, not HEAD
 #
 # Tweak sizes upward if you want to run very large workloads while still
 # exercising the disk tier (workload >> RAM is ideal for real disk testing).