diff --git a/README.md b/README.md
index 28c2c66..e9d14df 100644
--- a/README.md
+++ b/README.md
@@ -105,6 +105,14 @@ award-screen hook counts the awards, and one whose id matches
 line in the port file) makes the replayed ball log as `ball N (EXTRA BALL)`
 instead of advancing the count.
 
+**High scores**: when the game builds its high-score table report for Stern's
+agent (`/api/v1/game/high_score_events` — the endpoint the Insider gate sits
+on), the logger writes an `HSTD` line with all four players' scores. This is
+the report the game sends when a game has changed the table, so an `HSTD`
+line marks a high-score event without any new per-game RE; the entries
+themselves (initials, position) live deeper in the report and are not
+captured yet.
+
 **Mode detail**: the runtime polls each of the game's 22 mode objects' ACTIVE
 state per tick and logs START/END with the player's score at each edge —
 `mode_score=` is the score delta across the mode (approximate when other