diff --git a/docs/metadata-and-matching.md b/docs/metadata-and-matching.md
index 249ee23..f0f4e4c 100644
--- a/docs/metadata-and-matching.md
+++ b/docs/metadata-and-matching.md
@@ -48,6 +48,20 @@ Documentary versus scripted, and traditional versus CGI, need explicit values in
 - **Hardcoded channels:** saved state has fixed slots for `one`, `toonami` and `afterDark`, and only accepts 101 to 103. Adding channel 26 needs a generic channel list with a tested migration.
 - **Listed isn't playable:** a catalogue entry only proves a title is listed. Keep separate states for listed, source checked and failed, and recheck when tuning, as Orbit does now.
 
+## Library scale
+
+Paul's library is over 100,000 films and about 20,000 TV shows, as he reported on 1 November 2026. Episode count is unknown and could be far larger. The design has to hold at that size:
+
+- **Storage:** an indexed on-device database, not the saved setup file. Android's built-in SQLite needs no new dependency.
+- **Import:** paged in the background, resumable, throttled, and stopped by a rate-limit reply. Films and series first.
+- **Episodes:** fetched per series only when a series is approved or needed, not imported up front.
+- **Refresh:** changes since the last import, never a full re-read.
+- **Matching:** filter with provider queries or the local index, so no screen or schedule step scans the whole library in memory.
+- **Review screens:** show a short ranked list, with paging for the rest.
+- **Playback checks:** only for titles going onto a channel, never for the whole library.
+
+Real record sizes, box storage and provider limits still need measuring before these numbers are final.
+
 ## Recommendation engine design
 
 The engine should behave like a TV programmer who proposes and waits: it suggests from rules it can explain, and nothing reaches a channel until the viewer accepts it. It runs on the box, with no AI or cloud service.