Add --debug option to emit research CSVs

Add a --debug CLI flag to control writing of research CSVs alongside JSON exports. CLI: register --debug and pass write_debug_csv into run_live_capture; only write CSV/print CSV path when debug is enabled. Runner: add write_debug_csv parameter, skip writing CSVs and set csv_path to None when disabled, and avoid printing CSV lines for those exports. README: update live-capture docs to show JSON as the default export and note the --debug behavior for producing CSVs.

README.md

@@ -32,7 +32,9 @@ Live capture, Windows:
 .\run-exporter.ps1 --live
 ```
 
-Launch it before logging in, then open any supported history board in game. The tool keeps listening until you press any key. Exports are written under `exports\` as `Permanent_<date_time>.csv/json`, `Limited_<date_time>.csv/json`, or `Arc_<date_time>.csv/json`.
+Launch it before logging in, then open any supported history board in game. The tool keeps listening until you press any key. Exports are written under `exports\` as `Permanent_<date_time>.json`, `Limited_<date_time>.json`, or `Arc_<date_time>.json`.
+
+Pass `--debug` to also write the full research CSV next to each JSON export.
 
 If only one banner is captured, the export JSON is copied to the clipboard. If multiple banners are captured in the same run, clipboard copy is skipped so one banner does not overwrite another.
 

src/nte_history_exporter/cli.py

@@ -20,6 +20,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--flow-index", type=int, default=None)
     parser.add_argument("--interface-ip", default=None, help="local IPv4 address to bind for live capture")
     parser.add_argument("--no-clipboard", action="store_true", help="do not copy live exports to clipboard")
+    parser.add_argument("--debug", action="store_true", help="also write research CSVs next to the JSON exports")
     parser.add_argument(
         "--allow-boundary-records",
         action="store_true",
@@ -34,6 +35,7 @@ def main(argv: list[str] | None = None) -> int:
         result = run_live_capture(
             interface_ip=args.interface_ip,
             copy_clipboard=not args.no_clipboard,
+            write_debug_csv=args.debug,
         )
         for item in result["exports"]:
             export = item["export"]
@@ -69,6 +71,7 @@ def main(argv: list[str] | None = None) -> int:
         pair_count = len(decoded["pairs"])
 
     out_path, json_path = export_paths(kind)
+    if args.debug:
         write_csv(out_path, rows)
     export = build_export_json(
         rows,
@@ -80,6 +83,7 @@ def main(argv: list[str] | None = None) -> int:
     )
     json_path.write_text(json.dumps(export, ensure_ascii=False, indent=2), encoding="utf-8")
 
+    if args.debug:
         print(f"CSV written: {out_path}")
     print(f"JSON written: {json_path}")
     print(

src/nte_history_exporter/live_capture/runner.py

@@ -46,6 +46,7 @@ def run_live_capture(
     *,
     interface_ip: str | None = None,
     copy_clipboard: bool = True,
+    write_debug_csv: bool = False,
 ) -> dict:
     local_ip = interface_ip or detect_local_ipv4()
     session = LiveHistorySession(local_ip)
@@ -95,6 +96,7 @@ def run_live_capture(
             warnings = page_gap_warnings(pairs, best_run) + warnings
         pages_seen = [p[0] for p in best_run]
         csv_path, json_path = export_paths(kind)
+        if write_debug_csv:
             write_csv(csv_path, rows)
         export = build_export_json(
             rows,
@@ -104,7 +106,15 @@ def run_live_capture(
         )
         payload = json.dumps(export, ensure_ascii=False, indent=2)
         json_path.write_text(payload, encoding="utf-8")
-        exports.append({"kind": kind, "csv_path": csv_path, "json_path": json_path, "export": export, "payload": payload})
+        exports.append(
+            {
+                "kind": kind,
+                "csv_path": csv_path if write_debug_csv else None,
+                "json_path": json_path,
+                "export": export,
+                "payload": payload,
+            }
+        )
 
     if not exports:
         print("No Monopoly history pages were captured.")
@@ -118,6 +128,7 @@ def run_live_capture(
         print("Multiple banners captured; clipboard copy skipped.")
 
     for item in exports:
+        if item["csv_path"] is not None:
             print(f"CSV written: {item['csv_path']}")
         print(f"Export written: {item['json_path']}")
     return {"exports": exports}