Summary

• add a reproducible local-to-CUDA experiment workflow runbook
• add a wave-1 sweep launcher that isolates each run into its own working directory
• add a log parser that extracts stable metrics into a JSONL-friendly ledger format
• document the trainer log source-dump quirk in AGENTS.md so future tooling does not mis-parse template strings

Why

This PR is meant to support a disciplined experiment pipeline for new participants who want to go from local Apple Silicon smoke tests to leaderboard-oriented CUDA sweeps without changing the baseline trainer.

What changed

• docs/experiment_workflow.md
  • local Apple Silicon setup notes
  • verified MLX smoke result
  • wave-1 CUDA sweep plan
  • run isolation and ledger fields
• scripts/run_wave1_screen.sh
  • generates per-run directories under runs/
  • records command.sh and env.txt
  • supports --dry-run for sweep inspection
• scripts/extract_run_metrics.py
  • parses stable metric anchors from trainer logs
  • emits one JSON object per run
  • ignores the trainer's source-dump prefix by anchoring on runtime metric lines
• README.md
  • links the new experiment workflow from the Apple Silicon getting-started section
• .gitignore
  • ignores runs/
• AGENTS.md
  • records the log parsing surprise for future agents

Verification

bash -n scripts/run_wave1_screen.sh
python3 -m py_compile scripts/extract_run_metrics.py
bash scripts/run_wave1_screen.sh --dry-run
python3 scripts/extract_run_metrics.py logs/mlx_smoke.txt
python3 scripts/extract_run_metrics.py records/track_10min_16mb/2026-03-17_NaiveBaseline/train.log

Notes

• This PR intentionally does not change train_gpt.py or train_gpt_mlx.py.
• The sweep defaults target 1xH100 breadth screening first; 8xH100 confirmation is still the next step for real leaderboard attempts.