docs: Add README operator cache check

The README buried hit/miss verification under the SteamPrefill validation
chapter, and advertised make validate-check without a Makefile target.
Operators need a short start → traffic → metrics path against the existing
/metrics and /lancache-heartbeat endpoints.

Link: #29

Makefile

@@ -62,6 +62,32 @@ 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)
+	@echo "=== http://localhost/metrics ==="
+	@metrics=$$(curl -sf --max-time 5 http://localhost/metrics) || { \
+		echo "ERROR: could not fetch http://localhost/metrics"; \
+		echo "Is steamcache2 running on the default listen address :80?"; \
+		exit 1; \
+	}; \
+	printf '%s\n' "$$metrics"; \
+	echo ""; \
+	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 "ERROR: could not fetch http://localhost/lancache-heartbeat"; \
+		exit 1; \
+	}
+
 validate-kill: ## Kill leftover steamcache2 processes (safer, checks process name)
 	@echo "Looking for steamcache2 processes on common validation ports (80 is primary)..."
 	@for port in 80 8040 8080; do \
@@ -109,6 +135,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 "  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)"

README.md

@@ -53,6 +53,38 @@ SteamCache2 is a blazing fast download cache for Steam, designed to reduce bandw
    make run  # or ./steamcache2
    ```
 
+### Quick check: is it caching?
+
+After steamcache2 is running (default `listen_address: :80`) and has seen a little Steam traffic — a game download, a short SteamPrefill pass, or any cacheable request — confirm hits vs misses from the existing endpoints. You do not need a full benchmark or log diving.
+
+```bash
+make validate-check
+# or:
+curl -s http://localhost/metrics
+```
+
+Read these fields:
+
+| Field | Meaning |
+| --- | --- |
+| `cache_hits` / `cache_misses` / `hit_rate` | Whether later requests were served from cache |
+| `memory_cache_hits` / `disk_cache_hits` | Which tier served the hits |
+| `total_requests` / `errors` | Volume and failures |
+
+A first pass through new content is mostly misses (`hit_rate` near 0). Repeat the same content and `cache_hits` / `hit_rate` should rise.
+
+To confirm the process is up (HTTP 204 and `X-LanCache-Processed-By: SteamCache2`):
+
+```bash
+curl -s -i http://localhost/lancache-heartbeat
+```
+
+Use GET (`curl -i`), not HEAD (`curl -I`): the server only accepts GET.
+
+These are the cache process's own `/metrics` and `/lancache-heartbeat` endpoints. There is no separate metrics daemon.
+
+If you changed `listen_address`, point curl at that host:port instead. For a full SteamPrefill validation workflow (small caches, coalescing, GC), see [Validating Full Functionality](#validating-full-functionality-with-external-tools).
+
 ### Development Workflow
 
 Use `make` for the majority of common development tasks. The Makefile handles running tests, linting, hygiene checks, building, running the application, and other routine boilerplate work.
@@ -100,9 +132,11 @@ When finished, you can get a quick metrics summary with:
 
 ```bash
 make validate-check
+# or:
+curl -s http://localhost/metrics
 ```
 
-This is the recommended simple workflow. No automatic downloading or running of external tools.
+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.
 
 #### Inspecting the Result
 
@@ -115,9 +149,11 @@ curl -s http://localhost/metrics
 ```
 
 Look for:
-- High cache hit rate after the warmup pass
+- 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
+- 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`).
 
 #### The Validation Config
 
@@ -372,6 +408,16 @@ make
    - Consider using a different GC algorithm like `hybrid`
    - 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`
+   - 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)
+
 ### Getting Help
 
 - Check the logs for detailed error messages

docs/examples/validate-config.yaml

@@ -27,7 +27,9 @@
 #   SteamPrefill benchmark run -c 20 ...
 #
 # After the benchmark run, inspect with:
-#   curl -s http://localhost/metrics
+#   make validate-check
+#   # or: curl -s http://localhost/metrics
+# Heartbeat (process up): curl -s -i http://localhost/lancache-heartbeat
 #
 # 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).