docs: restructure API docs

README.md

@@ -13,44 +13,22 @@ To set up the UV module, you can run the following command:
 uv sync --frozen
 ```
 
-### Configuration
+## Usage
 
-1. **Copy the default configuration:**
+For detailed instructions on how to use the project, please refer to the **[API Documentation](docs/README.md)**.
+
+### Quick Start
+
+1. **Train a model:**
    ```bash
-   cp configs/default_ppo.yaml configs/my_experiment.yaml
+   uv run python scripts/train.py ppo.learning_rate=0.001 logging.track=true
    ```
 
-2. **Edit `configs/my_experiment.yaml`** to set your WandB credentials:
+2. **Monitor progress:**
-   ```yaml
+   See [Tracking & Monitoring](docs/api/tracking.md).
-   track: true  # Enable WandB logging
-   wandb_entity: "your-wandb-username"  # Replace with your username/team
-   wandb_project_name: "PPO-Modularity"
-   ```
 
-3. **(Optional) Login to WandB:**
+3. **Simulate a trained model:**
-   ```bash
+   See [Simulation & Evaluation](docs/api/simulation.md).
-   uv run wandb login
-   ```
-
-### Training
-
-example command:
-
-```bash
-uv run python scripts/train.py
-```
-
-Or use a custom config file:
-
-```bash
-uv run python scripts/train.py --config configs/my_experiment.yaml
-```
-
-Override specific parameters:
-
-```bash
-uv run python scripts/train.py --learning-rate 0.001 --num-envs 32 --track
-```
 
 ## HPC
 

docs/DEVELOPMENT.md

@@ -62,22 +62,9 @@ In the devcontainer, this will succeed on both CPU and GPU. A `GpuDevice` is exp
 
 ## Logging & Monitoring
 
-This project uses a unified logging system through the `experiment_logger` package. For a full API reference, see the [package README](../src/experiment_logger/README.md).
+This project uses a unified logging system through the `experiment_logger` package. 
-
-### Quick Setup
-
-1.  **Authorization**: Export your API key in your terminal to enable WandB synchronization:
-    ```bash
-    export WANDB_API_KEY=your_copied_api_key_here
-    ```
-2.  **Toggle Tracking**: Use the `--track` flag in `scripts/train.py` to enable online sync.
-3.  **Local Monitoring**: All runs are recorded in the `runs/` directory. View scalars with TensorBoard:
-    ```bash
-    tensorboard --logdir runs/
-    ```
-
-### Environment Awareness
-
-The logger automatically detects if it is running in an interactive terminal or a non-interactive environment (like an HPC Slurm job). It will automatically disable progress bars and switch to robust fallback modes (offline logging) to ensure your experiments never hang.
 
+- **Usage in Code**: To use the logger in your scripts, refer to the [package README](../src/experiment_logger/README.md) for the API reference.
+- **WandB/TensorBoard Setup**: For information on how to configure tracking for experiments, see the [Tracking & Monitoring API Guide](./api/tracking.md).
 
+The logger automatically detects if it is running in an interactive terminal or a non-interactive environment (like an HPC Slurm job), adjusting progress bars and fallback modes accordingly.

docs/README.md

@@ -2,6 +2,8 @@
 
 ## Design & architecture ([`/design`](./design/))
 
+If you are interested in the "why did you do it like this?"
+
 - [Actor/critic architecture](./design/actor-critic.md): Description of the actor-critic pipeline.
 - [Communication](./design/communication.md): Message propagation, Nerve-Net style.
 - [Controllers](./design/controllers.md): Macroscopig brain toplogy, centralized, arm-level, segment-level.
@@ -11,5 +13,9 @@
 
 ## API reference ([`/api`](./api/))
 
-- [Environment](./api/environment.md): MuJoCo environment interaction, state retrieval, and configuration.
+If you are interested in the "how do I use it?"
-- [Simulate](./api/simulate.md): Simulation rendering.
+
+- [Training](./api/training.md): How to configure and run experiments.
+- [Tracking & Monitoring](./api/tracking.md): Setting up WandB and TensorBoard to monitor runs.
+- [Simulation](./api/simulation.md): Visualizing and evaluating models.
+- [Environment](./api/environment.md): MuJoCo environment interaction and configuration.

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).