From 0cb463538e12785edf9d4846aba791ce98d7e4c7 Mon Sep 17 00:00:00 2001
From: Teagan Glenn <that@teagantotally.rocks>
Date: Wed, 22 Oct 2025 19:30:35 -0600
Subject: [PATCH] refactor(docs): share helper for README assertions

---
 README.md          | 20 ++++++++++++++++++++
 tests/test_docs.py | 26 +++++++++++++++++++++++---
 2 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 5d272a4..73f9d03 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,26 @@ Run continuously with a delay between runs:
 uv run load-data --continuous --delay 600
 ```
 
+### Configure live Plex access
+
+Provide the loader with your Plex and TMDb credentials when ingesting a live
+library. You can pass them as CLI options or export the mirrored environment
+variables before running the command:
+
+```bash
+uv run load-data \
+  --plex-url "https://plex.example.com" \
+  --plex-token "token-goes-here" \
+  --tmdb-api-key "tmdb-key" \
+  --qdrant-url http://localhost:6333
+```
+
+The flags above map directly to `PLEX_URL`, `PLEX_TOKEN`, and `TMDB_API_KEY`.
+Setting the environment variables keeps secrets out of shell history while the
+CLI options help with one-off runs. Specify `--plex-chunk-size` or its
+environment twin `PLEX_CHUNK_SIZE` when Plex servers throttle large fetches;
+smaller chunk sizes reduce request bursts at the cost of additional API calls.
+
 ### IMDb Retry Configuration
 The loader exposes CLI flags (and mirrored environment variables) that control
 how it retries IMDb lookups and how aggressively it backs off when hitting
diff --git a/tests/test_docs.py b/tests/test_docs.py
index 09e4c17..f3e8da7 100644
--- a/tests/test_docs.py
+++ b/tests/test_docs.py
@@ -2,6 +2,10 @@
 import pytest
 
 
+def read_readme() -> str:
+    return Path("README.md").read_text(encoding="utf-8")
+
+
 IMDB_RETRY_DOC_TOKENS = (
     "--imdb-cache",
     "IMDB_CACHE",
@@ -21,14 +25,30 @@
 
 
 def test_readme_documents_server_cache_and_reranker_settings():
-    readme = Path(__file__).resolve().parent.parent / "README.md"
-    content = readme.read_text(encoding="utf-8")
+    content = read_readme()
 
     for key in ("CACHE_SIZE", "USE_RERANKER", "PLEX_PLAYER_ALIASES"):
         assert key in content
 
 
+def test_readme_documents_live_plex_configuration_requirements() -> None:
+    readme = read_readme()
+
+    required_phrases = (
+        "### Configure live Plex access",
+        "--plex-url",
+        "--plex-token",
+        "--tmdb-api-key",
+        "PLEX_URL",
+        "PLEX_TOKEN",
+        "TMDB_API_KEY",
+    )
+
+    for phrase in required_phrases:
+        assert phrase in readme
+
+
 @pytest.mark.parametrize("token", IMDB_RETRY_DOC_TOKENS)
 def test_readme_documents_imdb_retry_controls(token: str) -> None:
-    readme = Path("README.md").read_text(encoding="utf-8")
+    readme = read_readme()
     assert token in readme