feat(summary): revision-gated cache with stale-while-revalidate (STATE-WP-0066)

Replace the fixed 15s TTL on GET /state/summary with per-table revision
watermarks, stale-while-revalidate background refresh, and a progress-tail
section split. SQLAlchemy write hooks invalidate core or progress sections
on mutation. Adds tests, benchmark script, and operator docs.

README.md

@@ -185,6 +185,14 @@ Returns a full snapshot in one call — used by both the MCP server and dashboar
 }
 ```
 
+**Caching:** responses are revision-gated — the API compares cheap per-table
+`MAX(updated_at)` / `MAX(created_at)` watermarks before rebuilding. Unchanged
+data returns the cached snapshot (`X-StateHub-Cache: hit-revision`). When core
+data changes, the last good snapshot may be served immediately while a
+background refresh runs (`X-StateHub-Cache: stale`). Force a synchronous rebuild
+with `?refresh=true` or `Cache-Control: no-cache`. Infrastructure probes should
+use `/state/health`, not `/state/summary`.
+
 ### Router summary
 
 | Prefix | Operations |