diff --git a/doc/README.md b/doc/README.md
index aa87381..7fa7bc2 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -193,6 +193,22 @@ seems to be activate_lot = 1 means wit check, 0 means guaranteed
 
 single_mode_wins_saddle defines titles (classic triple crown, tenno sweep, &c.) using win_saddle_type = 0
 
+race_instance is a combination of race, npc group, race date (month*100 + day), and time of day.
+it isn't actually anything i care about.
+
+which is to say, what i do care about is mapping races to each turn they're offered, and having a "race instance" enum like Hopeful-Stakes-Junior, Yasuda-Kinen-Classic, &c.
+
+single_mode_program defines the race instances available for each turn, but the year is expressed a bit weirdly in the race_permission column:
+- 1 = junior year
+- 2 = classic year
+- 3 = classic and senior year
+- 4 = senior year
+- 5 = ura finale
+
+grade_rate_id appears to be consistently 800 iff maiden race and 900 iff debut race, but the values particularly for g1s are all over the place.
+recommend_class_id appears to be consistently 1 iff maiden race or debut race, 2 iff pre-op, 3 iff op; but other values are confusing.
+so, it doesn't seem like there's a particular flag that identifies maiden races, despite the restrictions on when they appear in the ui.
+
 # trainee definitions
 
 - card_data has universal trainee stats: base skill set, stat growth bonuses ("talent"), default running style