docs: restructure docs for clarity

README.md

@@ -51,7 +51,7 @@ For detailed instructions on how to use the project, please refer to the **[API
 
 ## Results & Reproduction
 
-See **[docs/reproduction.md](docs/reproduction.md)** to learn how to access our public [Weights & Biases (WandB) project](https://wandb.ai/SEL3-2026-Groep-4/final-models-v2?nw=96mloffsyq), retrieve specific run parameters, and run the training/evaluation reproduction workflow.
+See **[docs/api/reproduction.md](docs/api/reproduction.md)** to learn how to access our public [Weights & Biases (WandB) project](https://wandb.ai/SEL3-2026-Groep-4/final-models-v2?nw=96mloffsyq), retrieve specific run parameters, and run the training/evaluation reproduction workflow.
 
 ## HPC
 

docs/README.md

@@ -8,7 +8,7 @@ For the core codebase, scripts, and contribution history, visit our [GitHub Repo
 
 - **[Installation Instructions](./DEVELOPMENT.md)**: Steps to set up your development environment locally or in a devcontainer using `uv`, including GPU configuration. For High-Performance Computing (HPC) setup details, see the **[HPC Guide](./HPC.md)**.
 - **[How to Run Experiments](./api/training.md)**: A complete guide on running training jobs, setting custom hyperparameters, and overriding config options using Hydra.
-- **[Results & Reproduction](./reproduction.md)**: Guide on how to access our public WandB training runs table and reproduce our training and evaluation phases (determining the best checkpoint vs. comparing architectures).
+- **[Results & Reproduction](./api/reproduction.md)**: Guide on how to access our public WandB training runs table and reproduce our training and evaluation phases (determining the best checkpoint vs. comparing architectures).
 - **[Repository Structure](#repository-structure)**: Overview of the directories and files within the codebase.
 
 ## Repository Structure
@@ -31,20 +31,21 @@ For the core codebase, scripts, and contribution history, visit our [GitHub Repo
 
 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.
+- [Actor-Critic Architecture](./design/actor-critic.md): Description of the actor-critic pipeline.
-- [Communication](./design/communication.md): Message propagation, Nerve-Net style.
+- [Communication Scheme](./design/communication.md): Message propagation, Nerve-Net style.
-- [Controllers](./design/controllers.md): Macroscopig brain toplogy, centralized, arm-level, segment-level.
+- [Modularity & Topology](./design/controllers.md): Macroscopic brain topology, centralized, arm-level, segment-level.
-- [Input/output](./design/input_action_spaces.md): Description of the model's input and output.
+- [Input & Action Spaces](./design/input_action_spaces.md): Description of the model's input and output.
-- [Learning algorithm](./design/learning_algorithm.md): RL techniques, i.e. PPO.
+- [Reinforcement Learning Algorithm](./design/learning_algorithm.md): RL techniques, i.e. PPO.
-- [Reward function](./design/reward_function.md): Goals, fitness tracking, and reward structures.
+- [Reward Function & Observation Space](./design/reward_function.md): Goals, fitness tracking, and reward structures.
 
 ## API reference (`/api`)
 
 If you are interested in the "how do I use it?"
 
-- [Training](./api/training.md): How to configure and run experiments.
+- [Brittle Star Environment](./api/environment.md): MuJoCo environment interaction and configuration.
+- [Training Models](./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.
+- [Checkpoint & Model Evaluation](./api/evaluation.md): Evaluating checkpoints and comparing fault tolerance.
-- [Environment](./api/environment.md): MuJoCo environment interaction and configuration.
+- [Interactive Simulation & Visualization](./api/simulation.md): Visualizing models in the MuJoCo viewer or rendering simulation videos.
-- [Analysis](./api/analysis.md): Comparing checkpoints and generating plots.
+- [Analysis & Plotting Tools](./api/analysis.md): Comparing checkpoints and generating plots.
-- [Evaluation](./api/evaluation.md): Evaluating checkpoints and comparing fault tolerance.
+- [Results & Reproduction](./api/reproduction.md): Accessing WandB results and running reproduction pipelines.

docs/api/reproduction.md

@@ -105,4 +105,4 @@ Once the best checkpoints for each architecture are identified, they are compare
    * **`reached_target`**: Navigational success rates.
    * **`arm_0` to `arm_4`**: Active segments per arm (indicating damage/amputations).
 
-This CSV can then be passed to the plotting scripts (e.g., `scripts/plots/analyze_comparisons.py`) to generate visualization plots. For details on configuration and outputs, see the **[Analysis & Plotting Guide](./api/analysis.md)**.
+This CSV can then be passed to the plotting scripts (e.g., `scripts/plots/analyze_comparisons.py`) to generate visualization plots. For details on configuration and outputs, see the **[Analysis & Plotting Guide](./analysis.md)**.

docs/api/simulation.md

@@ -1,6 +1,6 @@
-# Simulation & Evaluation
+# Interactive Simulation & Visualization
 
-The simulation pipeline allows you to visualize trained models and evaluate their performance under various conditions.
+The simulation pipeline allows you to visualize trained models and observe their behavior under various conditions.
 
 ## Overview
 
@@ -38,4 +38,4 @@ 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)**.
+For batch evaluation, checkpoint analysis, and cross-model architecture comparisons, see the **[Checkpoint & Model Evaluation Guide](./evaluation.md)**.

docs/api/training.md

@@ -53,10 +53,10 @@ uv run python scripts/train.py evaluation.evaluate_checkpoints=true
 
 ## Reproducing Experiments
 
-For detailed steps on how to reproduce training runs, locate run configuration metadata, or reproduce our experiments using Weights & Biases (WandB), see the **[Results & Reproduction Guide](../reproduction.md)**.
+For detailed steps on how to reproduce training runs, locate run configuration metadata, or reproduce our experiments using Weights & Biases (WandB), see the **[Results & Reproduction Guide](./reproduction.md)**.
 
 ---
 
-For more details on evaluation metrics and comparison tools, see [Evaluation](./evaluation.md).
+For more details on evaluation metrics and comparison tools, see [Checkpoint & Model Evaluation](./evaluation.md).
 
 For more details on tracking your experiments, see [Tracking & Monitoring](./tracking.md).

mkdocs.yml

@@ -2,6 +2,27 @@ site_name: Brittle Star Project
 theme:
   name: material
 
+nav:
+  - Home: README.md
+  - Design & Architecture:
+      - Actor-Critic Architecture: design/actor-critic.md
+      - Communication Scheme: design/communication.md
+      - Modularity & Topology: design/controllers.md
+      - Input & Action Spaces: design/input_action_spaces.md
+      - Reinforcement Learning Algorithm: design/learning_algorithm.md
+      - Reward Function & Observation Space: design/reward_function.md
+  - API Reference:
+      - Brittle Star Environment: api/environment.md
+      - Training Models: api/training.md
+      - Tracking & Monitoring: api/tracking.md
+      - Checkpoint & Model Evaluation: api/evaluation.md
+      - Interactive Simulation & Visualization: api/simulation.md
+      - Analysis & Plotting Tools: api/analysis.md
+      - Results & Reproduction: api/reproduction.md
+  - HPC Guide: HPC.md
+  - Contribution Guidelines: CONTRIBUTING.md
+  - Development Guide: DEVELOPMENT.md
+
 markdown_extensions:
   - pymdownx.superfences:
       custom_fences: