From e7ef89ef24b801ddef04bb3ae41263d71da699e2 Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Sun, 3 May 2026 17:32:15 +0200
Subject: [PATCH 01/15] chore: add MkDocs config

---
 mkdocs.yml | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 mkdocs.yml

diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..0da1eb3
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,3 @@
+site_name: Brittle Star Project
+theme:
+  name: material

From f87c696dac418746ed8c7b707300d17848801de4 Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Sun, 3 May 2026 17:37:38 +0200
Subject: [PATCH 02/15] ci: add workflow for publishing docs

---
 .github/workflows/publish-docs.yml | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
 create mode 100644 .github/workflows/publish-docs.yml

diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
new file mode 100644
index 0000000..b5b2b6b
--- /dev/null
+++ b/.github/workflows/publish-docs.yml
@@ -0,0 +1,20 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - main
+      - dev
+      - docs/*
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v2
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

From b1ef5125ce9bc48591f984d9dd86a4fcf55e06b3 Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Sun, 3 May 2026 17:43:34 +0200
Subject: [PATCH 03/15] fix: use personal token instead

Replaced GITHUB_TOKEN with PERSONAL_TOKEN for deployment.
---
 .github/workflows/publish-docs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
index b5b2b6b..a99390b 100644
--- a/.github/workflows/publish-docs.yml
+++ b/.github/workflows/publish-docs.yml
@@ -17,4 +17,4 @@ jobs:
       - name: Deploy docs
         uses: mhausenblas/mkdocs-deploy-gh-pages@master
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PERSONAL_TOKEN: ${{ secrets.PERSONAL_TOKEN }}

From cd411494d14d57bac1a89fbd2eed13d2d0d19397 Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Mon, 18 May 2026 20:47:52 +0200
Subject: [PATCH 04/15] docs: new publish workflow

---
 .github/workflows/publish-docs.yml | 27 +++++++++++++++++++++------
 mkdocs.yml                         |  7 +++++++
 2 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
index a99390b..177e04d 100644
--- a/.github/workflows/publish-docs.yml
+++ b/.github/workflows/publish-docs.yml
@@ -1,4 +1,5 @@
 name: Publish docs via GitHub Pages
+
 on:
   push:
     branches:
@@ -11,10 +12,24 @@ jobs:
     name: Deploy docs
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout main
-        uses: actions/checkout@v2
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ssh-key: ${{ secrets.DEPLOY_KEY }}
 
-      - name: Deploy docs
-        uses: mhausenblas/mkdocs-deploy-gh-pages@master
-        env:
-          PERSONAL_TOKEN: ${{ secrets.PERSONAL_TOKEN }}
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: pip install mkdocs-material
+
+      - name: Configure Git identity
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force
diff --git a/mkdocs.yml b/mkdocs.yml
index 0da1eb3..6c46844 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,3 +1,10 @@
 site_name: Brittle Star Project
 theme:
   name: material
+
+markdown_extensions:
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format

From e4869e0061fe2a169c33149f67b83a8ce0e093bd Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Tue, 19 May 2026 22:58:01 +0200
Subject: [PATCH 05/15] docs: fix non docs/ links

---
 .github/scripts/prepare_docs.py    | 35 ++++++++++++++++++++++++++++++
 .github/workflows/publish-docs.yml |  3 +++
 docs/CONTRIBUTING.md               |  2 +-
 docs/README.md                     |  2 +-
 4 files changed, 40 insertions(+), 2 deletions(-)
 create mode 100644 .github/scripts/prepare_docs.py

diff --git a/.github/scripts/prepare_docs.py b/.github/scripts/prepare_docs.py
new file mode 100644
index 0000000..bc3a47d
--- /dev/null
+++ b/.github/scripts/prepare_docs.py
@@ -0,0 +1,35 @@
+import os
+import glob
+import re
+import shutil
+
+folders_to_copy = ['src', 'scripts']
+for folder in folders_to_copy:
+    if os.path.exists(folder):
+        shutil.copytree(folder, f'docs/{folder}', dirs_exist_ok=True)
+
+for filepath in glob.glob('docs/**/*.md', recursive=True):
+    with open(filepath, 'r', encoding='utf-8') as f:
+        content = f.read()
+
+    # RULE A: Fix links pointing OUT to src/ or scripts/ 
+    # Logic: Because the folders were moved one level deeper, we remove exactly ONE '../'
+    content = re.sub(
+        r'\]\(\.\./((?:\.\./)*)(src|scripts)/([^)]*)\)', 
+        r'](\1\2/\3)', 
+        content
+    )
+
+    # RULE B: Fix links pointing FROM the copied files back TO the original docs/ folder
+    # Logic: Since these files are now inside docs/, the 'docs/' segment in the path is redundant.
+    content = re.sub(
+        r'\]\(((?:\.\./)+)docs/([^)]*)\)', 
+        r'](\1\2)', 
+        content
+    )
+
+    with open(filepath, 'w', encoding='utf-8') as f:
+        f.write(content)
+
+print("Successfully imported external files and adjusted markdown links.")
+
diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
index 177e04d..668c977 100644
--- a/.github/workflows/publish-docs.yml
+++ b/.github/workflows/publish-docs.yml
@@ -26,6 +26,9 @@ jobs:
       - name: Install dependencies
         run: pip install mkdocs-material
 
+      - name: Prepare external docs
+        run: python .github/scripts/prepare_docs.py
+
       - name: Configure Git identity
         run: |
           git config --global user.name "github-actions[bot]"
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index bd58706..5903790 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -24,7 +24,7 @@ Code readability is paramount, as code is read far more frequently than it is wr
 
 * **Git Practices:** Commits must be frequent and small. Each commit should relate to exactly one piece of functionality.
 * **Branching Strategy:** The `dev` branch serves as the integration branch for pushing and merging code. Only stable releases may be pushed to the `main` branch.
-* **Artifact Management:** Data files, trained models, and large datasets must never be committed directly to Git. Git Large File Storage (LFS) must be used for tracking large files. **All developers must have `git-lfs` installed locally** (see `DEVELOPMENT.md` for setup).
+* **Artifact Management:** Data files, trained models, and large datasets must never be committed directly to Git. Git Large File Storage (LFS) must be used for tracking large files. **All developers must have `git-lfs` installed locally** (see [DEVELOPMENT.md](./DEVELOPMENT.md) for setup).
 * **Repository Layout:** The repository must maintain the following core directories: `src/` for algorithms, `env/` for MuJoCo wrappers, `config/` for experiment configurations, `experiments/` for scripts, `docs/` for Doxygen or ReadTheDocs documentation, and `tests/` for unit tests.
 
 ## 4. Architecture & Tooling
diff --git a/docs/README.md b/docs/README.md
index 521cb28..237a1a5 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -9,7 +9,7 @@ If you are interested in the "why did you do it like this?"
 - [Controllers](./design/controllers.md): Macroscopig brain toplogy, centralized, arm-level, segment-level.
 - [Input/output](./design/input_action_spaces.md): Description of the model's input and output.
 - [Learning algorithm](./design/learning_algorithm.md): RL techniques, i.e. PPO.
-- [Reward function](./design/learning_algorithm.md): Goals, fitness tracking, and reward structures.
+- [Reward function](./design/reward_function.md): Goals, fitness tracking, and reward structures.
 
 ## API reference (`/api`)
 

From de6b0380028f22a9bff0ba3996efeab21543c430 Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Tue, 19 May 2026 23:04:41 +0200
Subject: [PATCH 06/15] docs: proper newlines formatting

---
 docs/DEVELOPMENT.md            | 4 +++-
 docs/HPC.md                    | 4 ++++
 docs/api/analysis.md           | 5 +++++
 docs/api/environment.md        | 6 ++++++
 docs/design/communication.md   | 1 +
 docs/design/reward_function.md | 3 +--
 6 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 3518b38..a6ba2a9 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -2,7 +2,7 @@
 
 This guide outlines how to set up the development environment for this project, prioritizing **reproducible builds**, **environment parity**, and **cross-hardware compatibility**.
 
-## Reproducibility &uv
+## Reproducibility & uv
 
 This project uses [uv](https://github.com/astral-sh/uv) to manage dependencies and virtual environments. The `uv.lock` file is the absolute source of truth for package versions and must always be committed.
 
@@ -48,6 +48,7 @@ The devcontainer provides an identical experience to local development but with
 ## Local Development (Alternative)
 
 If you prefer not to use Docker:
+
 1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
 2. Run `uv sync --frozen` (CPU) or `uv sync --frozen --extra cuda` (GPU).
 
@@ -58,6 +59,7 @@ Verify your setup by running the JAX initialization test:
 ```bash
 uv run pytest tests/test_jax_init.py
 ```
+
 In the devcontainer, this will succeed on both CPU and GPU. A `GpuDevice` is expected if a GPU is detected and the `cuda` extra was installed.
 
 ## Logging & Monitoring
diff --git a/docs/HPC.md b/docs/HPC.md
index 3e0e8d1..c4ebf6a 100644
--- a/docs/HPC.md
+++ b/docs/HPC.md
@@ -33,6 +33,7 @@ qsub -l gpus=1 scripts/hpc/install.sh
 Our scripts are cluster-agnostic and do **not** have hardcoded GPU requirements. Instead, you must request GPUs at runtime using the `-l gpus=1` flag when submitting to a production GPU cluster.
 
 ### Debugging (Donphan)
+
 The `donphan` cluster does not support GPUs. Simply run the scripts without extra resource flags:
 ```bash
 module swap cluster/donphan
@@ -40,6 +41,7 @@ qsub scripts/hpc/train.pbs
 ```
 
 ### Production (Joltik, Accelgor, Litleo)
+
 These clusters provide GPU acceleration and **require** a GPU request at runtime:
 ```bash
 module swap cluster/joltik  # or accelgor/litleo
@@ -64,11 +66,13 @@ After installation, run these commands to ensure your environment is set up corr
    ```bash
    ls -d venvs 2>/dev/null && echo "FAIL" || echo ">>> PASS: Project root is clean."
    ```
+
 2. **Verify Library Versions (NumPy Fix)**:
    ```bash
    python -c "import numpy; print(f'NumPy: {numpy.__version__}')"
    # Expected: 2.x.x (Venv version), not 1.2x (System version)
    ```
+
 3. **Verify GPU Access**:
    ```bash
    python -c "import torch, jax; print(f'GPU: {torch.cuda.is_available()}'); print(f'JAX: {jax.devices()}')"
diff --git a/docs/api/analysis.md b/docs/api/analysis.md
index e852295..9c88895 100644
--- a/docs/api/analysis.md
+++ b/docs/api/analysis.md
@@ -5,6 +5,7 @@ This guide outlines the tools available for analyzing experimental data and gene
 ## Shared Configuration
 
 All plotting scripts share a central configuration in `scripts/plots/plot_config.py`. This file defines:
+
 - **Color Palette:** A color-blind friendly, high-contrast palette for different architectures.
 - **Typography:** Consistent font sizes and styles tailored for A0 posters.
 - **Markers:** Shared visual indicators, such as the ★ used for best performers.
@@ -40,6 +41,7 @@ uv run python scripts/plots/analyze_comparisons.py path/to/results.csv \
 ### Outputs
 
 The script generates four key plots, each saved as both `.png` and `.svg`:
+
 1.  **Forward Velocity:** Grouped bar chart (cm/s).
 2.  **Accumulated Reward:** Mean cumulative reward.
 3.  **Success Rate:** Target acquisition percentage.
@@ -65,6 +67,7 @@ uv run python scripts/plots/analyze_convergence.py --output_dir runs/convergence
 ### Outputs
 
 Generates three plots (PNG & SVG):
+
 1. `convergence_comparison`: Grouped horizontal bar chart.
 2. `progress_reward_curves`: Line plots of reward over time.
 3. `progress_velocity_curves`: Line plots of velocity over time.
@@ -74,7 +77,9 @@ Generates three plots (PNG & SVG):
 ## Poster Integration (Figma)
 
 ### SVG & Scaling
+
 We recommend using the **SVG** outputs for poster design in Figma:
+
 1. **No Resolution Loss:** SVGs are vector-based and will remain sharp at any size.
 2. **Native Text:** Text in the SVG imports as native text layers in Figma.
 3. **Exact Font Matching:** To ensure a `28pt` font in the plot matches a `28pt` font in your poster, set the `--fig_width` and `--fig_height` to match the physical dimensions of the plot box in your Figma layout.
diff --git a/docs/api/environment.md b/docs/api/environment.md
index 470732d..e54a698 100644
--- a/docs/api/environment.md
+++ b/docs/api/environment.md
@@ -1,12 +1,15 @@
 # Brittle star environment
 
 ## Creation
+
 The environment package contains a factory class `BrittleStarEnvFactory` 
 that creates instances of the environment/morphologies/... It uses the
 configuration classes defined in `env_config.py` to create the instances.
 
 ## Configuration
+
 The data classes in `env_config` have default values as stated in the tutorials.
+
 * MorphologyConfig: configuration for the morphology of the brittle star. Contains
 number of arms, number of segments per arm, and control mode.
 * ArenaConfig: configuration for the arena. Sets the size of the arena, whether to 
@@ -15,10 +18,13 @@ set the ground floor to sand, attach a target and sizes of the walls.
 such as camera locations, simulation time and the task.
 
 ## Backend and Task enums
+
 The Backend enum specifies either an MJC or MJX backend.
+
 * MJC: runs on CPU
 * MJX: uses jax on the gpu
 
 The Task enum specifies which task to use. 2 items are present:
+
 * DIRECTED_LOCOMOTION: move to a target location
 * LIGHT_ESCAPE: situation where the robot must move to a darker location
diff --git a/docs/design/communication.md b/docs/design/communication.md
index 4a9cc82..73b1220 100644
--- a/docs/design/communication.md
+++ b/docs/design/communication.md
@@ -1,6 +1,7 @@
 # Communication scheme (Message Passing)
 
 Remember our research question:
+
 > "What is the impact of different levels of controller modularity on learning speed, coordination, and fault tolerance
 > (e.g. amputations) in brittle-star-like robots trained with Reinforcement Learning?"
 
diff --git a/docs/design/reward_function.md b/docs/design/reward_function.md
index 9cf178f..afbf18b 100644
--- a/docs/design/reward_function.md
+++ b/docs/design/reward_function.md
@@ -8,8 +8,7 @@ inputs must be distributed fairly to guarantee an objective comparison between d
 - The reward function is centered around minimizing the distance to the goal or maximizing the movement towards the goal
   within a finite number of timesteps $T$.
 - To motivate efficient movement, the amount of timesteps taken to reach the goal will be used as penalty.
-- An extra penalty based on movement relative to the current step and
-the previous is used to penalize a movement away from the target.
+- An extra penalty based on movement relative to the current step and the previous is used to penalize a movement away from the target.
 
 ## From reward to PPO
 

From 97598105e5d5e7e70cdd709ca5a7363d0301b7eb Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Tue, 19 May 2026 23:11:20 +0200
Subject: [PATCH 07/15] docs: latex and urls

---
 docs/HPC.md                       |  2 +-
 docs/README.md                    |  4 ++++
 docs/api/tracking.md              |  2 +-
 docs/design/actor-critic.md       |  8 ++++----
 docs/design/communication.md      |  4 ++--
 docs/design/learning_algorithm.md |  6 +++---
 docs/javascripts/mathjax.js       | 18 ++++++++++++++++++
 mkdocs.yml                        |  6 ++++++
 8 files changed, 39 insertions(+), 11 deletions(-)
 create mode 100644 docs/javascripts/mathjax.js

diff --git a/docs/HPC.md b/docs/HPC.md
index c4ebf6a..e7a3372 100644
--- a/docs/HPC.md
+++ b/docs/HPC.md
@@ -1,6 +1,6 @@
 # HPC Guide
 
-Full documentation: <https://docs.hpc.ugent.be/>
+Full documentation: [https://docs.hpc.ugent.be/](https://docs.hpc.ugent.be/)
 
 ## Storage Overview
 
diff --git a/docs/README.md b/docs/README.md
index 237a1a5..df66859 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,5 +1,9 @@
 # Documentation
 
+Welcome to the Brittle Star project documentation. This codebase contains the implementations and research for the scientific evaluation of controller modularity in brittle-star-like robots trained using Reinforcement Learning.
+
+For the core codebase, scripts, and contribution history, visit our [GitHub Repository](https://github.com/SELab-3-2026/SEL3-2026-Groep-4).
+
 ## Design & architecture (`/design`)
 
 If you are interested in the "why did you do it like this?"
diff --git a/docs/api/tracking.md b/docs/api/tracking.md
index 226992b..00eed22 100644
--- a/docs/api/tracking.md
+++ b/docs/api/tracking.md
@@ -47,7 +47,7 @@ All runs are recorded locally in the `runs/` directory (or the directory specifi
 tensorboard --logdir runs/
 ```
 
-Access the interface at `http://localhost:6006`.
+Access the interface at [http://localhost:6006](http://localhost:6006).
 
 ### CLI Exploration Tool
 
diff --git a/docs/design/actor-critic.md b/docs/design/actor-critic.md
index 245fefd..d27dbc3 100644
--- a/docs/design/actor-critic.md
+++ b/docs/design/actor-critic.md
@@ -98,7 +98,7 @@ graph TD
 
 ## Implementation Details (Network Depth)
 
-Inspired by: https://iclr-blog-track.github.io/2022/03/25/ppo-implementation-details/
+Inspired by: [PPO Implementation Details](https://iclr-blog-track.github.io/2022/03/25/ppo-implementation-details/)
 
 The MLPs used in both pipelines are defined with specific hidden layer configurations to balance learning capability
 and computational cost. As of right now, though this might change as we make progress in our experiments, we use:
@@ -116,6 +116,6 @@ by previous research to maintain learning stability.
 
 **References**
 
-- Ha, D. (2017, October 29). A Visual Guide to Evolution Strategies. 大トロ ・ Machine Learning. https://blog.otoro.net/2017/10/29/visual-evolution-strategies/
-- Schulman, John, Filip Wolski, Prafulla Dhariwal, Alec Radford, and Oleg Klimov. ‘Proximal Policy Optimization Algorithms’. arXiv:1707.06347. Preprint, arXiv, 28 August 2017. https://doi.org/10.48550/arXiv.1707.06347.
-- Wang, Tingwu, Renjie Liao, Jimmy Ba, and S. Fidler. ‘NerveNet: Learning Structured Policy with Graph Neural Networks’. Conference paper presented at International Conference on Learning Representations. 15 February 2018. https://www.semanticscholar.org/paper/NerveNet:-Learning-Structured-Policy-with-Graph-Wang-Liao/249408527106d7595d45dd761dd53c83e5a02613.
+- Ha, D. (2017, October 29). A Visual Guide to Evolution Strategies. 大トロ ・ Machine Learning. [https://blog.otoro.net/2017/10/29/visual-evolution-strategies/](https://blog.otoro.net/2017/10/29/visual-evolution-strategies/)
+- Schulman, John, Filip Wolski, Prafulla Dhariwal, Alec Radford, and Oleg Klimov. ‘Proximal Policy Optimization Algorithms’. arXiv:1707.06347. Preprint, arXiv, 28 August 2017. [https://doi.org/10.48550/arXiv.1707.06347](https://doi.org/10.48550/arXiv.1707.06347).
+- Wang, Tingwu, Renjie Liao, Jimmy Ba, and S. Fidler. ‘NerveNet: Learning Structured Policy with Graph Neural Networks’. Conference paper presented at International Conference on Learning Representations. 15 February 2018. [https://www.semanticscholar.org/paper/NerveNet:-Learning-Structured-Policy-with-Graph-Wang-Liao/249408527106d7595d45dd761dd53c83e5a02613](https://www.semanticscholar.org/paper/NerveNet:-Learning-Structured-Policy-with-Graph-Wang-Liao/249408527106d7595d45dd761dd53c83e5a02613).
diff --git a/docs/design/communication.md b/docs/design/communication.md
index 73b1220..377de89 100644
--- a/docs/design/communication.md
+++ b/docs/design/communication.md
@@ -40,5 +40,5 @@ extended morphologies.
 
 **References**
 
-- Wang, Tingwu, Renjie Liao, Jimmy Ba, and S. Fidler. ‘NerveNet: Learning Structured Policy with Graph Neural Networks’. Conference paper presented at International Conference on Learning Representations. 15 February 2018. https://www.semanticscholar.org/paper/NerveNet:-Learning-Structured-Policy-with-Graph-Wang-Liao/249408527106d7595d45dd761dd53c83e5a02613.
-- Huang, Wenlong, Igor Mordatch, and Deepak Pathak. ‘One Policy to Control Them All: Shared Modular Policies for Agent-Agnostic Control’. arXiv:2007.04976. Preprint, arXiv, 9 July 2020. https://doi.org/10.48550/arXiv.2007.04976.
+- Wang, Tingwu, Renjie Liao, Jimmy Ba, and S. Fidler. ‘NerveNet: Learning Structured Policy with Graph Neural Networks’. Conference paper presented at International Conference on Learning Representations. 15 February 2018. [https://www.semanticscholar.org/paper/NerveNet:-Learning-Structured-Policy-with-Graph-Wang-Liao/249408527106d7595d45dd761dd53c83e5a02613](https://www.semanticscholar.org/paper/NerveNet:-Learning-Structured-Policy-with-Graph-Wang-Liao/249408527106d7595d45dd761dd53c83e5a02613).
+- Huang, Wenlong, Igor Mordatch, and Deepak Pathak. ‘One Policy to Control Them All: Shared Modular Policies for Agent-Agnostic Control’. arXiv:2007.04976. Preprint, arXiv, 9 July 2020. [https://doi.org/10.48550/arXiv.2007.04976](https://doi.org/10.48550/arXiv.2007.04976).
diff --git a/docs/design/learning_algorithm.md b/docs/design/learning_algorithm.md
index 1b5c2f5..afee110 100644
--- a/docs/design/learning_algorithm.md
+++ b/docs/design/learning_algorithm.md
@@ -25,6 +25,6 @@ Alternative learning algorithms include:
 
 **References**
 
-- Fujimoto, Scott, Herke Hoof, and David Meger. ‘Addressing Function Approximation Error in Actor-Critic Methods’. Proceedings of the 35th International Conference on Machine Learning, 3 July 2018, 1587-96. https://proceedings.mlr.press/v80/fujimoto18a.html.
-- Huang, Wenlong, Igor Mordatch, and Deepak Pathak. ‘One Policy to Control Them All: Shared Modular Policies for Agent-Agnostic Control’. arXiv:2007.04976. Preprint, arXiv, 9 July 2020. https://doi.org/10.48550/arXiv.2007.04976.
-- Schulman, John, Filip Wolski, Prafulla Dhariwal, Alec Radford, and Oleg Klimov. ‘Proximal Policy Optimization Algorithms’. arXiv:1707.06347. Preprint, arXiv, 28 August 2017. https://doi.org/10.48550/arXiv.1707.06347.
+- Fujimoto, Scott, Herke Hoof, and David Meger. ‘Addressing Function Approximation Error in Actor-Critic Methods’. Proceedings of the 35th International Conference on Machine Learning, 3 July 2018, 1587-96. [https://proceedings.mlr.press/v80/fujimoto18a.html](https://proceedings.mlr.press/v80/fujimoto18a.html).
+- Huang, Wenlong, Igor Mordatch, and Deepak Pathak. ‘One Policy to Control Them All: Shared Modular Policies for Agent-Agnostic Control’. arXiv:2007.04976. Preprint, arXiv, 9 July 2020. [https://doi.org/10.48550/arXiv.2007.04976](https://doi.org/10.48550/arXiv.2007.04976).
+- Schulman, John, Filip Wolski, Prafulla Dhariwal, Alec Radford, and Oleg Klimov. ‘Proximal Policy Optimization Algorithms’. arXiv:1707.06347. Preprint, arXiv, 28 August 2017. [https://doi.org/10.48550/arXiv.1707.06347](https://doi.org/10.48550/arXiv.1707.06347).
diff --git a/docs/javascripts/mathjax.js b/docs/javascripts/mathjax.js
new file mode 100644
index 0000000..f5e96e7
--- /dev/null
+++ b/docs/javascripts/mathjax.js
@@ -0,0 +1,18 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document.addEventListener("DOMContentLoaded", () => {
+  MathJax.startup.document.state(0);
+  MathJax.typesetClear();
+  MathJax.typesetPromise();
+});
diff --git a/mkdocs.yml b/mkdocs.yml
index 6c46844..3084148 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -8,3 +8,9 @@ markdown_extensions:
         - name: mermaid
           class: mermaid
           format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.arithmatex:
+      generic: true
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

From f26312583af1f1e2ad060b13755042a1ae03f3de Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Tue, 19 May 2026 23:17:17 +0200
Subject: [PATCH 08/15] fix: switch to katex

---
 docs/javascripts/katex.js   | 16 ++++++++++++++++
 docs/javascripts/mathjax.js | 18 ------------------
 mkdocs.yml                  |  8 ++++++--
 3 files changed, 22 insertions(+), 20 deletions(-)
 create mode 100644 docs/javascripts/katex.js
 delete mode 100644 docs/javascripts/mathjax.js

diff --git a/docs/javascripts/katex.js b/docs/javascripts/katex.js
new file mode 100644
index 0000000..956b86a
--- /dev/null
+++ b/docs/javascripts/katex.js
@@ -0,0 +1,16 @@
+const renderMath = (el) => {
+  renderMathInElement(el, {
+    delimiters: [
+      { left: "$$",  right: "$$",  display: true },
+      { left: "$",   right: "$",   display: false },
+      { left: "\\(", right: "\\)", display: false },
+      { left: "\\[", right: "\\]", display: true }
+    ],
+  });
+};
+
+if (typeof document$ !== "undefined") {
+  document$.subscribe(({ body }) => renderMath(body));
+} else {
+  document.addEventListener("DOMContentLoaded", () => renderMath(document.body));
+}
diff --git a/docs/javascripts/mathjax.js b/docs/javascripts/mathjax.js
deleted file mode 100644
index f5e96e7..0000000
--- a/docs/javascripts/mathjax.js
+++ /dev/null
@@ -1,18 +0,0 @@
-window.MathJax = {
-  tex: {
-    inlineMath: [["\\(", "\\)"]],
-    displayMath: [["\\[", "\\]"]],
-    processEscapes: true,
-    processEnvironments: true
-  },
-  options: {
-    ignoreHtmlClass: ".*|",
-    processHtmlClass: "arithmatex"
-  }
-};
-
-document.addEventListener("DOMContentLoaded", () => {
-  MathJax.startup.document.state(0);
-  MathJax.typesetClear();
-  MathJax.typesetPromise();
-});
diff --git a/mkdocs.yml b/mkdocs.yml
index 3084148..7e6c856 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -11,6 +11,10 @@ markdown_extensions:
   - pymdownx.arithmatex:
       generic: true
 
+extra_css:
+  - https://unpkg.com/katex@0/dist/katex.min.css
+
 extra_javascript:
-  - javascripts/mathjax.js
-  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
+  - javascripts/katex.js
+  - https://unpkg.com/katex@0/dist/katex.min.js
+  - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js

From 9f99470557fcfb584e4e51a95698f09689b08e9d Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Tue, 19 May 2026 23:26:48 +0200
Subject: [PATCH 09/15] docs: experiment reproduction

---
 README.md            |  7 ++++---
 docs/README.md       | 23 +++++++++++++++++++++++
 docs/api/training.md | 27 +++++++++++++++++++++++++++
 3 files changed, 54 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 45bdf63..a683f16 100644
--- a/README.md
+++ b/README.md
@@ -22,9 +22,10 @@ uv sync --frozen
 ├── runs/                   # Default output directory for Hydra and training artifacts
 ├── scripts/                # High-level entrypoints for training, simulation, and evaluation
 ├── src/
-│   └── brittle_star_project/ # Core library and environment logic
-│       ├── evaluation/     # Checkpoint evaluation, rollout logic, and metrics persistence
-│       └── trainers/       # Training loop implementations (e.g., PPO)
+│   ├── brittle_star_project/ # Core library and environment logic
+│   │   ├── evaluation/     # Checkpoint evaluation, rollout logic, and metrics persistence
+│   │   └── trainers/       # Training loop implementations (e.g., PPO)
+│   └── experiment_logger/  # Standalone logging package
 └── tests/                  # Unit and integration tests
 ```
 
diff --git a/docs/README.md b/docs/README.md
index df66859..4367711 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,6 +4,29 @@ Welcome to the Brittle Star project documentation. This codebase contains the im
 
 For the core codebase, scripts, and contribution history, visit our [GitHub Repository](https://github.com/SELab-3-2026/SEL3-2026-Groep-4).
 
+## Core Requirements & Guides
+
+- **[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.
+- **[Reproducing Experiments](./api/training.md#reproducing-experiments)**: Best practices for reproducing past training runs using exact seeds, dependencies, and automatic metadata logging.
+- **[Repository Structure](#repository-structure)**: Overview of the directories and files within the codebase.
+
+## Repository Structure
+
+```text
+.
+├── configs/                # Hydra configuration files (YAML)
+├── docs/                   # Comprehensive documentation and API guides
+├── runs/                   # Default output directory for Hydra and training artifacts
+├── scripts/                # High-level entrypoints for training, simulation, and evaluation
+├── src/
+│   ├── brittle_star_project/ # Core library and environment logic
+│   │   ├── evaluation/     # Checkpoint evaluation, rollout logic, and metrics persistence
+│   │   └── trainers/       # Training loop implementations (e.g., PPO)
+│   └── experiment_logger/  # Standalone logging package
+└── tests/                  # Unit and integration tests
+```
+
 ## Design & architecture (`/design`)
 
 If you are interested in the "why did you do it like this?"
diff --git a/docs/api/training.md b/docs/api/training.md
index d3e6c51..e892ea2 100644
--- a/docs/api/training.md
+++ b/docs/api/training.md
@@ -15,6 +15,7 @@ The project uses a modular configuration system powered by [Hydra](https://hydra
    ```
 
 2. **Edit `configs/experiment/my_experiment.yaml`** to set your experiment parameters:
+
    ```yaml
    # @package _global_
    experiment:
@@ -50,6 +51,32 @@ By default, the trainer saves checkpoints but does not evaluate them. To enable
 uv run python scripts/train.py evaluation.evaluate_checkpoints=true
 ```
 
+## Reproducing Experiments
+
+To ensure scientific validity and allow other researchers to reproduce your training runs, follow these steps:
+
+1. **Lock Environment Dependencies**:
+   Always use the exact environment lockfile when running experiments. Run:
+   ```bash
+   uv sync --frozen
+   ```
+   This guarantees that the same package versions (including JAX, Flax, and MuJoCo) are used.
+
+2. **Save and Locate Configuration Metadata**:
+   Every time you start a training run, the configuration is fully resolved by Hydra and saved as a metadata YAML file:
+   - For checkpointed steps: `runs/<run_dir>/checkpoints/<prefix>_step_<step>_metadata.yaml`
+   - For the final model: `runs/<run_dir>/final_model_metadata.yaml`
+
+   This metadata file contains every active hyperparameter (e.g., learning rate, morphology configuration, PPO parameters, etc.) for that specific run.
+
+3. **Re-Run with Pinning**:
+   To reproduce a run, execute the training script with the configuration parameters specified in the metadata file, making sure to reuse the same seed:
+   ```bash
+   uv run python scripts/train.py experiment=my_experiment ppo.learning_rate=0.001 experiment.seed=42
+   ```
+
+---
+
 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).

From 731ad4fd843f50a7dffeb2452e38c969e116f5f7 Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Tue, 19 May 2026 23:29:21 +0200
Subject: [PATCH 10/15] fix: remove trailing whitespace

---
 .github/scripts/prepare_docs.py | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/.github/scripts/prepare_docs.py b/.github/scripts/prepare_docs.py
index bc3a47d..f83dd4c 100644
--- a/.github/scripts/prepare_docs.py
+++ b/.github/scripts/prepare_docs.py
@@ -12,19 +12,19 @@ for filepath in glob.glob('docs/**/*.md', recursive=True):
     with open(filepath, 'r', encoding='utf-8') as f:
         content = f.read()
 
-    # RULE A: Fix links pointing OUT to src/ or scripts/ 
+    # RULE A: Fix links pointing OUT to src/ or scripts/
     # Logic: Because the folders were moved one level deeper, we remove exactly ONE '../'
     content = re.sub(
-        r'\]\(\.\./((?:\.\./)*)(src|scripts)/([^)]*)\)', 
-        r'](\1\2/\3)', 
+        r'\]\(\.\./((?:\.\./)*)(src|scripts)/([^)]*)\)',
+        r'](\1\2/\3)',
         content
     )
 
     # RULE B: Fix links pointing FROM the copied files back TO the original docs/ folder
     # Logic: Since these files are now inside docs/, the 'docs/' segment in the path is redundant.
     content = re.sub(
-        r'\]\(((?:\.\./)+)docs/([^)]*)\)', 
-        r'](\1\2)', 
+        r'\]\(((?:\.\./)+)docs/([^)]*)\)',
+        r'](\1\2)',
         content
     )
 

From 1ca6dd31294f13ad68d027e4c67fac2c420050ed Mon Sep 17 00:00:00 2001
From: Robin Meersman <echteenrobin@gmail.com>
Date: Wed, 20 May 2026 13:25:29 +0200
Subject: [PATCH 11/15] fix: formatting

---
 .github/scripts/prepare_docs.py | 23 +++++++----------------
 1 file changed, 7 insertions(+), 16 deletions(-)

diff --git a/.github/scripts/prepare_docs.py b/.github/scripts/prepare_docs.py
index f83dd4c..3cb0a2b 100644
--- a/.github/scripts/prepare_docs.py
+++ b/.github/scripts/prepare_docs.py
@@ -3,33 +3,24 @@ import glob
 import re
 import shutil
 
-folders_to_copy = ['src', 'scripts']
+folders_to_copy = ["src", "scripts"]
 for folder in folders_to_copy:
     if os.path.exists(folder):
-        shutil.copytree(folder, f'docs/{folder}', dirs_exist_ok=True)
+        shutil.copytree(folder, f"docs/{folder}", dirs_exist_ok=True)
 
-for filepath in glob.glob('docs/**/*.md', recursive=True):
-    with open(filepath, 'r', encoding='utf-8') as f:
+for filepath in glob.glob("docs/**/*.md", recursive=True):
+    with open(filepath, "r", encoding="utf-8") as f:
         content = f.read()
 
     # RULE A: Fix links pointing OUT to src/ or scripts/
     # Logic: Because the folders were moved one level deeper, we remove exactly ONE '../'
-    content = re.sub(
-        r'\]\(\.\./((?:\.\./)*)(src|scripts)/([^)]*)\)',
-        r'](\1\2/\3)',
-        content
-    )
+    content = re.sub(r"\]\(\.\./((?:\.\./)*)(src|scripts)/([^)]*)\)", r"](\1\2/\3)", content)
 
     # RULE B: Fix links pointing FROM the copied files back TO the original docs/ folder
     # Logic: Since these files are now inside docs/, the 'docs/' segment in the path is redundant.
-    content = re.sub(
-        r'\]\(((?:\.\./)+)docs/([^)]*)\)',
-        r'](\1\2)',
-        content
-    )
+    content = re.sub(r"\]\(((?:\.\./)+)docs/([^)]*)\)", r"](\1\2)", content)
 
-    with open(filepath, 'w', encoding='utf-8') as f:
+    with open(filepath, "w", encoding="utf-8") as f:
         f.write(content)
 
 print("Successfully imported external files and adjusted markdown links.")
-

From 4fb21bbbb77d35a15d3305107e5b989bf12bf139 Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Wed, 20 May 2026 14:42:13 +0200
Subject: [PATCH 12/15] docs: reproduce results

---
 README.md            |   4 ++
 docs/README.md       |   2 +-
 docs/api/training.md |  22 +--------
 docs/reproduction.md | 108 +++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 114 insertions(+), 22 deletions(-)
 create mode 100644 docs/reproduction.md

diff --git a/README.md b/README.md
index a683f16..9bb9ee2 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,10 @@ For detailed instructions on how to use the project, please refer to the **[API
 4. **Compare fault tolerance of models:**
    See [Checkpoint & Model Evaluation](docs/api/evaluation.md)
 
+## 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.
+
 ## HPC
 
 See **[docs/HPC.md](docs/HPC.md)** for the full guide, including environment setup, cluster selection, interactive debugging, and job submission.
diff --git a/docs/README.md b/docs/README.md
index 4367711..1e0c21d 100644
--- a/docs/README.md
+++ b/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.
-- **[Reproducing Experiments](./api/training.md#reproducing-experiments)**: Best practices for reproducing past training runs using exact seeds, dependencies, and automatic metadata logging.
+- **[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).
 - **[Repository Structure](#repository-structure)**: Overview of the directories and files within the codebase.
 
 ## Repository Structure
diff --git a/docs/api/training.md b/docs/api/training.md
index e892ea2..a3b813a 100644
--- a/docs/api/training.md
+++ b/docs/api/training.md
@@ -53,27 +53,7 @@ uv run python scripts/train.py evaluation.evaluate_checkpoints=true
 
 ## Reproducing Experiments
 
-To ensure scientific validity and allow other researchers to reproduce your training runs, follow these steps:
-
-1. **Lock Environment Dependencies**:
-   Always use the exact environment lockfile when running experiments. Run:
-   ```bash
-   uv sync --frozen
-   ```
-   This guarantees that the same package versions (including JAX, Flax, and MuJoCo) are used.
-
-2. **Save and Locate Configuration Metadata**:
-   Every time you start a training run, the configuration is fully resolved by Hydra and saved as a metadata YAML file:
-   - For checkpointed steps: `runs/<run_dir>/checkpoints/<prefix>_step_<step>_metadata.yaml`
-   - For the final model: `runs/<run_dir>/final_model_metadata.yaml`
-
-   This metadata file contains every active hyperparameter (e.g., learning rate, morphology configuration, PPO parameters, etc.) for that specific run.
-
-3. **Re-Run with Pinning**:
-   To reproduce a run, execute the training script with the configuration parameters specified in the metadata file, making sure to reuse the same seed:
-   ```bash
-   uv run python scripts/train.py experiment=my_experiment ppo.learning_rate=0.001 experiment.seed=42
-   ```
+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)**.
 
 ---
 
diff --git a/docs/reproduction.md b/docs/reproduction.md
new file mode 100644
index 0000000..f6fba01
--- /dev/null
+++ b/docs/reproduction.md
@@ -0,0 +1,108 @@
+# Results & Reproduction
+
+This guide explains how to access our official training logs and reproduce our results.
+
+Our official training runs, model configurations, and metrics are publicly hosted on Weights & Biases (WandB).
+
+---
+
+## Weights & Biases (WandB) Project
+
+All experiments, final models, and training logs are tracked in our public WandB project:
+
+* **Official Runs Table**: [WandB final-models-v2 Table](https://wandb.ai/SEL3-2026-Groep-4/final-models-v2/table?nw=96mloffsyq)
+
+This page lists the verified runs with their architecture types, morphology definitions, evaluation metrics, and final model performance.
+
+### How to Reproduce a Run from WandB
+
+Weights & Biases provides a built-in feature to extract the exact parameters and commands used for any given run:
+
+1. Open the [WandB final-models-v2 Table](https://wandb.ai/SEL3-2026-Groep-4/final-models-v2/table?nw=96mloffsyq).
+2. Click on the name of the run you wish to reproduce to open its detail page.
+3. In the top-right corner of the run header (next to the run name, not the main workspace header), click the **three dots (`...`)** menu.
+4. Select **"Reproduce run"**. This will display the exact command-line arguments and configuration settings used to execute that run.
+
+---
+
+## Local & HPC Reproduction Workflow
+
+To reproduce our training and evaluation phases locally or on an HPC cluster, follow the procedures below.
+
+### 1. Environment Setup
+
+To ensure identical package versions (including JAX, Flax, and MuJoCo), sync your environment using the lockfile:
+
+```bash
+uv sync --frozen
+```
+
+### 2. Training Phase
+
+Run the training script using the exact parameters retrieved from WandB's "Reproduce run" page or from a downloaded `_metadata.yaml` file:
+
+```bash
+uv run python scripts/train.py experiment=my_experiment ppo.learning_rate=0.001 experiment.seed=42
+```
+
+---
+
+## Evaluation Phases
+
+Reproducing our evaluation results is divided into two distinct phases:
+
+### Phase 1: Determining the Best Checkpoint
+
+During training, checkpoints are saved at regular intervals. To determine which of these checkpoints performed the best:
+
+1. **Evaluate Checkpoints Post-Training**:
+   If checkpoint evaluation was not run during training, scan the completed run's checkpoints folder by pointing to the final model path:
+
+   ```bash
+   uv run python scripts/evaluate_checkpoints.py simulation.model_path=runs/your_run_dir/final_model.flax
+   ```
+
+   This script runs deterministic rollouts for every checkpoint in `runs/your_run_dir/checkpoints/`.
+
+2. **Locate the Results**:
+   The evaluations are saved to:
+
+   ```text
+   runs/your_run_dir/metrics/checkpoint_evaluation.csv
+   ```
+
+   Analyze this CSV to find the checkpoint iteration with the highest average return or target success rate. This checkpoint will be used for cross-architecture comparisons.
+
+### Phase 2: Comparing Checkpoints Between Architectures
+
+Once the best checkpoints for each architecture are identified, they are compared under shared, standardized environments (including fault tolerance checks such as leg amputations).
+
+1. **Configure the Comparison Models**:
+   Open or create an evaluation config file (e.g., `configs/evaluation/poster.yaml`) and add the paths to the best checkpoints:
+
+   ```yaml
+   # configs/evaluation/poster.yaml
+   evaluation:
+     comparison_models:
+       - runs/run_arch_centralized/checkpoints/checkpoint_best.flax
+       - runs/run_arch_decentralized/checkpoints/checkpoint_best.flax
+   ```
+
+2. **Execute the Comparison Script**:
+   Run the comparison script using your config:
+
+   ```bash
+   uv run python scripts/compare_models.py evaluation=poster
+   ```
+
+   This script runs multiple sequential evaluation episodes (defined by `comparison_num_episodes` starting at `comparison_base_seed`) for every model across the selected morphologies.
+
+3. **Analyze Comparison Metrics**:
+   The script writes a consolidated CSV file to `metrics/model_comparison.csv` containing:
+
+   * **`eval_return`**: The cumulative return.
+   * **`approx_max_velocity`**: The distance covered per step.
+   * **`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)**.

From 511c3ebd958682b8d16d7d6863e4fda6c52f42a1 Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Wed, 20 May 2026 14:54:01 +0200
Subject: [PATCH 13/15] docs: restructure docs for clarity

---
 README.md                      |  2 +-
 docs/README.md                 | 25 +++++++++++++------------
 docs/{ => api}/reproduction.md |  2 +-
 docs/api/simulation.md         |  6 +++---
 docs/api/training.md           |  4 ++--
 mkdocs.yml                     | 21 +++++++++++++++++++++
 6 files changed, 41 insertions(+), 19 deletions(-)
 rename docs/{ => api}/reproduction.md (99%)

diff --git a/README.md b/README.md
index 9bb9ee2..6e56334 100644
--- a/README.md
+++ b/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
 
diff --git a/docs/README.md b/docs/README.md
index 1e0c21d..ec73a8f 100644
--- a/docs/README.md
+++ b/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.
-- [Communication](./design/communication.md): Message propagation, Nerve-Net style.
-- [Controllers](./design/controllers.md): Macroscopig brain toplogy, centralized, arm-level, segment-level.
-- [Input/output](./design/input_action_spaces.md): Description of the model's input and output.
-- [Learning algorithm](./design/learning_algorithm.md): RL techniques, i.e. PPO.
-- [Reward function](./design/reward_function.md): Goals, fitness tracking, and reward structures.
+- [Actor-Critic Architecture](./design/actor-critic.md): Description of the actor-critic pipeline.
+- [Communication Scheme](./design/communication.md): Message propagation, Nerve-Net style.
+- [Modularity & Topology](./design/controllers.md): Macroscopic brain topology, centralized, arm-level, segment-level.
+- [Input & Action Spaces](./design/input_action_spaces.md): Description of the model's input and output.
+- [Reinforcement Learning Algorithm](./design/learning_algorithm.md): RL techniques, i.e. PPO.
+- [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.
-- [Environment](./api/environment.md): MuJoCo environment interaction and configuration.
-- [Analysis](./api/analysis.md): Comparing checkpoints and generating plots.
-- [Evaluation](./api/evaluation.md): Evaluating checkpoints and comparing fault tolerance.
\ No newline at end of file
+- [Checkpoint & Model Evaluation](./api/evaluation.md): Evaluating checkpoints and comparing fault tolerance.
+- [Interactive Simulation & Visualization](./api/simulation.md): Visualizing models in the MuJoCo viewer or rendering simulation videos.
+- [Analysis & Plotting Tools](./api/analysis.md): Comparing checkpoints and generating plots.
+- [Results & Reproduction](./api/reproduction.md): Accessing WandB results and running reproduction pipelines.
\ No newline at end of file
diff --git a/docs/reproduction.md b/docs/api/reproduction.md
similarity index 99%
rename from docs/reproduction.md
rename to docs/api/reproduction.md
index f6fba01..87df150 100644
--- a/docs/reproduction.md
+++ b/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)**.
diff --git a/docs/api/simulation.md b/docs/api/simulation.md
index 1e288b9..bde8b93 100644
--- a/docs/api/simulation.md
+++ b/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)**.
diff --git a/docs/api/training.md b/docs/api/training.md
index a3b813a..197e76f 100644
--- a/docs/api/training.md
+++ b/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).
diff --git a/mkdocs.yml b/mkdocs.yml
index 7e6c856..cc60194 100644
--- a/mkdocs.yml
+++ b/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:

From f569f4c008819bf741523c827aee5566e8c5601e Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Wed, 20 May 2026 15:00:50 +0200
Subject: [PATCH 14/15] docs: cleanup and extra references

---
 .github/scripts/prepare_docs.py | 6 +++---
 docs/README.md                  | 1 +
 docs/api/evaluation.md          | 4 ++++
 docs/api/tracking.md            | 4 ++++
 docs/api/training.md            | 2 ++
 5 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/.github/scripts/prepare_docs.py b/.github/scripts/prepare_docs.py
index 3cb0a2b..7460d48 100644
--- a/.github/scripts/prepare_docs.py
+++ b/.github/scripts/prepare_docs.py
@@ -3,7 +3,7 @@ import glob
 import re
 import shutil
 
-folders_to_copy = ["src", "scripts"]
+folders_to_copy = ["src", "scripts", "configs" ]
 for folder in folders_to_copy:
     if os.path.exists(folder):
         shutil.copytree(folder, f"docs/{folder}", dirs_exist_ok=True)
@@ -12,9 +12,9 @@ for filepath in glob.glob("docs/**/*.md", recursive=True):
     with open(filepath, "r", encoding="utf-8") as f:
         content = f.read()
 
-    # RULE A: Fix links pointing OUT to src/ or scripts/
+    # RULE A: Fix links pointing OUT to src/, scripts/, or configs/
     # Logic: Because the folders were moved one level deeper, we remove exactly ONE '../'
-    content = re.sub(r"\]\(\.\./((?:\.\./)*)(src|scripts)/([^)]*)\)", r"](\1\2/\3)", content)
+    content = re.sub(r"\]\(\.\./((?:\.\./)*)(src|scripts|configs)/([^)]*)\)", r"](\1\2/\3)", content)
 
     # RULE B: Fix links pointing FROM the copied files back TO the original docs/ folder
     # Logic: Since these files are now inside docs/, the 'docs/' segment in the path is redundant.
diff --git a/docs/README.md b/docs/README.md
index ec73a8f..c2edd2f 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -9,6 +9,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](./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).
+- **[Contribution Guidelines](./CONTRIBUTING.md)**: Standards, rules, and best practices for developing and adding code to the repository.
 - **[Repository Structure](#repository-structure)**: Overview of the directories and files within the codebase.
 
 ## Repository Structure
diff --git a/docs/api/evaluation.md b/docs/api/evaluation.md
index 45b880e..1828a7f 100644
--- a/docs/api/evaluation.md
+++ b/docs/api/evaluation.md
@@ -54,3 +54,7 @@ python scripts/evaluate_checkpoints.py \
 ```
 
 This script scans the `checkpoints/` directory of the specified run and evaluates every `.flax` file it finds using the model's training morphology.
+
+---
+
+For a step-by-step walkthrough on using these evaluation phases to reproduce our project results, see the **[Results & Reproduction Guide](./reproduction.md)**.
diff --git a/docs/api/tracking.md b/docs/api/tracking.md
index 00eed22..77178f7 100644
--- a/docs/api/tracking.md
+++ b/docs/api/tracking.md
@@ -58,3 +58,7 @@ 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).
+
+## Developer Logging API
+
+For details on the developer API of our internal logging library (how backend routing, checkpoint synchronization, and singleton initialization works), see the **[Experiment Logger API Guide](../../src/experiment_logger/README.md)**.
diff --git a/docs/api/training.md b/docs/api/training.md
index 197e76f..b93b910 100644
--- a/docs/api/training.md
+++ b/docs/api/training.md
@@ -6,6 +6,8 @@ This guide covers how to configure and run training experiments for the Brittle
 
 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.
 
+For a detailed guide on the structure, validation, and usage of our Hydra configuration files, see the **[Brittle Star Configuration System Guide](../../configs/README.md)**.
+
 ### Creating a Custom Experiment
 
 1. **Create a new experiment file:**

From 50bc3bf20b8a8f354b0811c9bcebcd2a1c2c2df3 Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Wed, 20 May 2026 15:24:10 +0200
Subject: [PATCH 15/15] Update docs/design/actor-critic.md

Co-authored-by: RobinMeersman <77965843+RobinMeersman@users.noreply.github.com>
---
 docs/design/actor-critic.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/design/actor-critic.md b/docs/design/actor-critic.md
index d27dbc3..8d03912 100644
--- a/docs/design/actor-critic.md
+++ b/docs/design/actor-critic.md
@@ -104,7 +104,7 @@ The MLPs used in both pipelines are defined with specific hidden layer configura
 and computational cost. As of right now, though this might change as we make progress in our experiments, we use:
 
 - Input Networks (Sensors & Feature Extractors): These networks map the raw state inputs to internal hidden states.
-  They are configured as standard dense networks with 2 hidden layers of 64 nodes each (`[64, 64]`) and utilize `tanh`
+  They are configured as standard dense networks with 3 hidden layers of 300 nodes each (`[300, 300, 300]`) and utilize `tanh`
   activation functions.
 - Output Networks (Motors, Actors & Critics): The final output models are intentionally kept shallow. The Actor
   directly projects the hidden state to a continuous action distribution (`mean` and `log_std`) using a single dense