Document nuPlan download, conversion, and replay usage

[eugenevinitsky]

What

• Adds docs/nuplan_data.md: how to get the nuPlan mini split (maps + mini DBs, no sensor blobs), how conversion to PufferDrive .bin works (external py123d converter — repo URL and exact invocation left as clearly-flagged maintainer TODOs, with a reduced-parallelism RAM note), the expected flat nuplan__<token>.bin output layout, an example replay training command (--env.map-dir / --env.num-maps / --env.simulation-mode replay / --env.control-mode control_sdc_only / --env.scenario-length 200, mirroring [eval.validation_replay]), and how to enable the nuPlan evaluators (inline via enabled = true + local env.map_dir, or standalone via puffer eval --evaluator).
• Extends the README ## Data section with bullets for the WOMD download scripts (data_utils/download_womd_data.py, data_utils/download_database_gcp.sh) and a pointer to docs/nuplan_data.md.
• Adds AGENTIC_PR per repo convention for agent-created PRs.

Why

There was no documentation for obtaining nuPlan data or converting it to PufferDrive .bin files; the converter is external tooling referenced only in commit messages, and its default parallelism OOMs on small-RAM machines. This writes down what is verifiable from the repo and flags the rest as maintainer-supplied.

Notes

• Merge-order dependency: the "Enabling the nuPlan evals" section describes [eval.validation_replay] and [eval.behaviors_full_dir] as shipping disabled with placeholder env.map_dir values — that is the state after the sibling PR fix/drive-ini-remove-hardcoded-scratch-paths lands. On this branch's base, drive.ini still has enabled = true and /scratch/ev2237 paths. Do not merge this PR before the sibling PR.
• Converter provenance is stated only as far as reachable history supports it: CARLA town bins converted via py123d (c2667356); the nuPlan behavior-category eval bins referenced by the config were a py123d v0.2.1 reconvert (2b1d3ecb). The checked-in sample nuPlan bin's converter version is not recorded, so the doc does not claim one. Converter repo URL and invocation are explicit TODO placeholders — nothing invented.
• Verification: every cited file, line range, and config key was grepped in this worktree — drive.py:268-273 (map_dir dir-or-single-.bin) and :368-369 (num_maps fail-fast) exact; all example flags exist in drive.ini [env]; sample bin, WOMD scripts, and docs/evaluation.md evaluator flow confirmed. Docs-only change, no runtime risk.

🤖 Generated with Claude Code

🤖 Generated with Claude Code

[eugenevinitsky]

Filled in the converter placeholders with the real pipeline: py123d (download + arrow parse, per its nuPlan guide) → 123Drive (uv run convert --preset nuplan --py123d_path ... --output ...). Includes the RAM guidance: --workers defaults to 80% of cores with one parsed log in memory per worker, and --preset nuplan pins 20 s log chunking to avoid OOM — which addresses the reported conversion crashes.

[eugenevinitsky]

Folded into #525 — the nuPlan doc now lives there alongside the fetch script it references (single reviewable unit for data onboarding).