Add sample_random_scans script and first-page list-scans option

- scripts/sample_random_scans.sh: pick a random scan per machine (default: first list page) and download mosaic and/or tiles
- --list-scans-first-page-only: one HTTP request for scan list (up to 320 IDs)
- scripts/machines.example.txt; .gitignore local machines.txt (copy from example)
- README: document usage

spruce/cli.py

@@ -105,6 +105,14 @@ def parse_args() -> argparse.Namespace:
         action="store_true",
         help="Print all scans for --machine and exit",
     )
+    p.add_argument(
+        "--list-scans-first-page-only",
+        action="store_true",
+        help=(
+            "With --list-scans: only fetch the first list page (up to 320 scans) "
+            "— one HTTP request, no pagination"
+        ),
+    )
     p.add_argument(
         "--recheck",
         action="store_true",
@@ -134,6 +142,9 @@ def main() -> None:
     if args.verbose:
         logging.getLogger().setLevel(logging.DEBUG)
 
+    if args.list_scans_first_page_only and not args.list_scans:
+        sys.exit("--list-scans-first-page-only requires --list-scans")
+
     # --list-machines doesn't need credentials
     if args.list_machines:
         base_url = "http://205.149.147.131:8010/"
@@ -213,7 +224,8 @@ def main() -> None:
         sess = MachineSession(machines[0], config)
         if not sess.login():
             sys.exit("Login failed.")
-        scans = sess.get_all_scans()
+        first_only = bool(args.list_scans_first_page_only)
+        scans = sess.get_all_scans(first_page_only=first_only)
         print(f"{'ID':>8}  {'Date':<22}  {'Name':<40}  {'Status'}")
         print("-" * 85)
         for sc in scans:
@@ -221,7 +233,8 @@ def main() -> None:
                 f"{sc['scan_id']:>8}  {sc.get('scan_time', ''):<22}  "
                 f"{sc.get('name', ''):<40}  {sc.get('status', '')}"
             )
-        print(f"\nTotal: {len(scans)} scans")
+        total_note = " (first page only — not full archive)" if first_only else ""
+        print(f"\nTotal: {len(scans)} scans{total_note}")
         return
 
     log.info(