docs: Repository structure

docs/api/evaluation.md

@@ -0,0 +1,47 @@
+# Checkpoint & Model Evaluation
+
+This guide covers how to evaluate trained brittle star models, both during training and as a post-training analysis step.
+
+## Checkpoint Evaluation (During Training)
+
+The `PPOTrainer` can automatically evaluate every saved checkpoint using the fast MJX backend. This is enabled via configuration.
+
+### Configuration
+
+In your experiment config or via CLI:
+```bash
+python scripts/train.py evaluation.evaluate_checkpoints=true evaluation.eval_max_steps=5000
+```
+
+Results are saved to `runs/<run_dir>/metrics/checkpoint_evaluation.csv` and synced to Weights & Biases if enabled.
+
+## Cross-Model Comparison
+
+To compare different architectures or runs, use `scripts/compare_models.py`.
+
+1. Create or update a YAML file in `configs/evaluation/`.
+2. Run the Comparison:
+
+```bash
+python scripts/compare_models.py evaluation=poster
+```
+
+The script will run the specified number of episodes for each model and produce a single CSV with return and velocity metrics.
+
+## Post-hoc Checkpoint Evaluation
+
+If you didn't enable evaluation during training, or want to re-run it with different settings, use `scripts/evaluate_checkpoints.py`.
+
+```bash
+python scripts/evaluate_checkpoints.py \
+    simulation.model_path=runs/<run_id>/final_model.flax \
+    evaluation.eval_seed=42
+```
+
+This script scans the `checkpoints/` directory and evaluates every `.flax` file it finds.
+
+## Metrics Explained
+
+- **`eval_return`**: The accumulated shaped reward using the `reward_fn` defined in `PPOTrainer`.
+- **`approx_max_velocity`**: Calculated as `(initial_dist - final_dist) / total_steps`. Note that this is an average velocity over the episode.
+- **`reached_target`**: Boolean indicating if the robot reached the target within the max steps.

docs/api/simulation.md

@@ -37,3 +37,5 @@ uv run scripts/simulate.py \
 
 Videos and evaluation metadata are stored in timestamped folders alongside the model:
 `runs/your_run/final_model_evaluations/eval_<timestamp>/simulation.mp4`
+
+For batch evaluation and cross-model comparison, see the **[Evaluation Guide](./evaluation.md)**.

docs/api/training.md

@@ -38,12 +38,18 @@ To run with your custom experiment file:
 uv run python scripts/train.py experiment=my_experiment
 ```
 
-### Command-Line Overrides
-
-You can override any parameter directly from the command line using Hydra's dot notation. This is useful for quick tests:
-
 ```bash
 uv run python scripts/train.py ppo.learning_rate=0.001 ppo.num_envs=32 logging.track=true
 ```
 
+## Evaluation During Training
+
+By default, the trainer saves checkpoints but does not evaluate them. To enable automatic headless evaluation of every saved checkpoint, set `evaluation.evaluate_checkpoints=true`:
+
+```bash
+uv run python scripts/train.py evaluation.evaluate_checkpoints=true
+```
+
+For more details on evaluation metrics and comparison tools, see [Evaluation](./evaluation.md).
+
 For more details on tracking your experiments, see [Tracking & Monitoring](./tracking.md).