Docs for strangers: real quick start, own-shelves guide, clone-safe stub guard

README rewritten for a fresh clone: working status, quick start with
env-var table and per-stage commands, photo-taking guidance, a
bring-your-own-shelves section (this repo carries the author's live
data), tokenless workflows, and a dev section. New committed
data/STUB_DATA.marker closes a real gap: the cache marker is
gitignored, so a fresh clone had stub-derived to_add.csv with no
guard — upload now refuses on either marker. Username docs: BGG_USERNAME
in .env is the one place it's needed; config.toml is a fallback.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

scripts/write_photo_fixtures.py

@@ -20,6 +20,11 @@ from pathlib import Path
 from bggpipe.bgg_client import cache_key
 
 TARGETS = (Path("tests/fixtures/bgg_cache"), Path("data/bgg_cache"))
+
+# Committed alongside the stub-derived CSVs (the cache markers are
+# gitignored, so this is what protects a fresh clone): upload refuses to
+# run while it exists.
+DATA_MARKER = Path("data/STUB_DATA.marker")
 SEARCH_TYPES = "boardgame,boardgameexpansion"
 
 BG, EXP = "boardgame", "boardgameexpansion"
@@ -363,7 +368,16 @@ def main() -> None:
             "This cache contains hand-written stub XML, not real BGG "
             "responses. Data resolved from it must not be uploaded.\n"
         )
+    DATA_MARKER.parent.mkdir(parents=True, exist_ok=True)
+    DATA_MARKER.write_text(
+        "The CSVs in this directory were resolved from hand-written stub "
+        "fixtures, not real BGG data — version_ids are SYNTHETIC. The "
+        "upload stage refuses to run while this file exists. Delete it "
+        "only after re-resolving against real recorded fixtures "
+        "(BGG_API_TOKEN + scripts/record_fixtures.py + resolve --force).\n"
+    )
     print(f"Wrote {len(files)} fixture file(s) to {' and '.join(map(str, TARGETS))}")
+    print(f"Wrote {DATA_MARKER} (committed; upload refuses while it exists)")
 
 
 if __name__ == "__main__":