docs: restructure API docs

docs/api/simulate.md

@@ -1,14 +0,0 @@
-# Training and Simulation for Brittle Star Models
-
-## Simulating a model
-
-In order to simulate and view the behavior of a trained model, you can use the `simulate.py` script. This script allows you to specify the path to a trained model and will launch a simulation using that model. This script has the following parameters:
-
-- `--model`: The path to the trained model artifact to simulate.
-- `--model-type`: The type of model to simulate (e.g., `random`, ...)
-- `--task`: The task to simulate (e.g., `directed_locomotion`, ...)
-- `--seed`: The random seed for reproducibility.
-
-```bash
-python simulate.py --model artifacts/my_model --model-type random --task directed_locomotion --seed 0
-```

docs/api/simulation.md

@@ -0,0 +1,39 @@
+# Simulation & Evaluation
+
+The simulation pipeline allows you to visualize trained models and evaluate their performance under various conditions.
+
+## Overview
+
+The simulation pipeline is metadata-driven. Training-specific configurations (morphology, arena, environment, etc.) are automatically loaded from the `_metadata.yaml` file associated with the model checkpoint.
+
+## Basic Simulation
+
+To simulate a model in the MuJoCo viewer:
+
+```bash
+uv run scripts/simulate.py simulation.model_path=runs/your_run/final_model.flax
+```
+
+## Amputation & Morphology Overrides
+
+You can test trained models on different morphologies (e.g., amputating legs) by providing a morphology override. The observations will be automatically padded up to the training morphology's dimensions:
+
+```bash
+uv run scripts/simulate.py \
+    simulation.model_path=runs/your_run/final_model.flax \
+    simulation.morphology_override=configs/morphology/3_arms.yaml
+```
+
+## Video Recording
+
+Recording videos requires the `[evaluation]` extra:
+
+```bash
+uv run scripts/simulate.py \
+    simulation.model_path=runs/your_run/final_model.flax \
+    simulation.record_video=true \
+    simulation.max_steps=1000
+```
+
+Videos and evaluation metadata are stored in timestamped folders alongside the model:
+`runs/your_run/final_model_evaluations/eval_<timestamp>/simulation.mp4`

docs/api/tracking.md

@@ -0,0 +1,60 @@
+# Tracking & Monitoring
+
+This guide explains how to monitor your experiments using Weights & Biases (WandB) and TensorBoard.
+
+## Weights & Biases (WandB)
+
+WandB is used for online synchronization and visualization of training metrics.
+
+### Authorization
+
+Export your API key in your terminal to enable WandB synchronization:
+
+```bash
+export WANDB_API_KEY=your_copied_api_key_here
+```
+
+Alternatively, you can log in using the CLI:
+
+```bash
+uv run wandb login
+```
+
+### Enabling Tracking
+
+To enable online sync during a training run, set `logging.track=true` on the command line:
+
+```bash
+uv run python scripts/train.py logging.track=true
+```
+
+You can also configure your project and entity:
+
+```bash
+uv run python scripts/train.py \
+    logging.track=true \
+    logging.wandb_project_name="MyProject" \
+    logging.wandb_entity="my-team"
+```
+
+These can also be set in your configuration YAML file under the `logging` key.
+
+## Local Monitoring with TensorBoard
+
+All runs are recorded locally in the `runs/` directory (or the directory specified in `experiment.base_run_dir`). You can view scalars and other metrics with TensorBoard:
+
+```bash
+tensorboard --logdir runs/
+```
+
+Access the interface at `http://localhost:6006`.
+
+### CLI Exploration Tool
+
+For quick diagnostics or to export data to CSV without launching the full TensorBoard UI, you can use the `explore_tensorboard.py` script:
+
+```bash
+uv run python scripts/analysis/explore_tensorboard.py runs/your_run_name/
+```
+
+See the detailed description in [`/scripts/analysis/README.md`](../../scripts/analysis/README.md).

docs/api/training.md

@@ -0,0 +1,49 @@
+# Training Models
+
+This guide covers how to configure and run training experiments for the Brittle Star project using Hydra-based configurations.
+
+## Configuration
+
+The project uses a modular configuration system powered by [Hydra](https://hydra.cc/). Instead of passing many command-line flags, you select and override configuration groups.
+
+### Creating a Custom Experiment
+
+1. **Create a new experiment file:**
+   Create a file at `configs/experiment/my_experiment.yaml`. You can copy an existing one as a template:
+   ```bash
+   cp configs/experiment/base.yaml configs/experiment/my_experiment.yaml
+   ```
+
+2. **Edit `configs/experiment/my_experiment.yaml`** to set your experiment parameters:
+   ```yaml
+   # @package _global_
+   experiment:
+     exp_name: "my_custom_run"
+     seed: 42
+   ```
+
+## Training Execution
+
+To start a training run with the default settings defined in `configs/main_config.yaml`:
+
+```bash
+uv run python scripts/train.py
+```
+
+### Using a Custom Experiment Configuration
+
+To run with your custom experiment file:
+
+```bash
+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
+```
+
+For more details on tracking your experiments, see [Tracking & Monitoring](./tracking.md).