From 71aedc4853d666b944f54f2d706af6e09a13a73d Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Tue, 14 Apr 2026 22:47:09 +0200
Subject: [PATCH] docs: add main configuration entry point and usage guidelines

---
 configs/README.md        | 53 +++++++++++++++++++++++++++++++---------
 configs/main_config.yaml | 13 ++++++++++
 2 files changed, 54 insertions(+), 12 deletions(-)
 create mode 100644 configs/main_config.yaml

diff --git a/configs/README.md b/configs/README.md
index 58c6aed..21f95b1 100644
--- a/configs/README.md
+++ b/configs/README.md
@@ -1,23 +1,52 @@
-# Configuration Files
+# Brittle Star Configuration System
 
-This directory contains configuration files for training experiments.
+This project uses **Hydra** for a modular, hierarchical, and strictly-typed configuration system.
 
-## Usage
+## Core Concepts
 
-Use `--config` with `scripts/train.py` to run an experiment:
+1.  **Composition over Inheritance**: Instead of one giant config file, the configuration is composed of small, domain-specific modules (PPO settings, architecture, morphology, etc.).
+2.  **Strict Typing**: Every configuration is validated against a Python dataclass schema (`ConfigStore`). Misspelled keys throw a `ConfigAttributeError` immediately.
+3.  **CLI Swapping**: You can swap entire modules or override individual values from the command line without touching code.
 
+## Directory Structure
+
+- `main_config.yaml`: The root entry point defining the default composition.
+- `experiment/`: High-level experiment settings (seed, device).
+- `logging/`: WandB and checkpointing configuration.
+- `ppo/`: PPO training hyperparameters.
+- `architecture/`: Polymorphic network architectures (centralized vs. decentralized).
+- `morphology/`: Physical robot definitions (number of segments, amputations).
+- `arena/`: Environment physics and visual settings.
+- `environment/`: Task-specific settings (Directed Locomotion, Light Escape).
+
+## Common Commands
+
+### Local Debugging
+Run a quick test with minimal iterations:
 ```bash
-python scripts/train.py --config configs/default_ppo.yaml
+python scripts/train.py experiment=dev_test ppo=fast
 ```
 
-You can overriding settings via CLI:
+### Swapping Architectures or Morphologies
+Test a decentralized controller on a 3-arm robot:
 ```bash
-python scripts/train.py --config configs/default_ppo.yaml --learning-rate 0.001
+python scripts/train.py architecture=decentralized morphology=3_arms
 ```
 
-## Available Configurations
+### HPC Production
+Run stable PPO with WandB enabled (HPC submission scripts handle the `hydra.run.dir` redirection):
+```bash
+python scripts/train.py ppo=stable logging=wandb_enabled
+```
 
-- `default_ppo.yaml`: Baseline config.
-- `dev_test.yaml`: Fast iteration for development.
-- `production_training.yaml`: Full-scale training.
-- `personal_template.yaml`: Template for team members to customize.
+### Dry-Run Validation
+Check if your configuration is valid without starting the simulation:
+```bash
+python scripts/train.py --cfg job
+```
+
+## Developer Notes
+
+- **Adding a new group**: Create a subdirectory in `configs/` and register the new dataclass in `src/brittle_star_project/configs/register_configs.py`.
+- **Typo Catching**: If you see a `ConfigAttributeError`, check for typos in your YAML keys or CLI overrides.
+- **Output Redirection**: Hydra automatically creates `outputs/` directories. On HPC, ensure `hydra.run.dir` is set to a fast scratch storage.
diff --git a/configs/main_config.yaml b/configs/main_config.yaml
new file mode 100644
index 0000000..0583327
--- /dev/null
+++ b/configs/main_config.yaml
@@ -0,0 +1,13 @@
+# Brittle Star Project - Main Configuration
+# This file defines the default composition of the hierarchical configuration.
+# Sub-configs are loaded from the relative directories.
+
+defaults:
+  - experiment: base
+  - logging: default
+  - ppo: default
+  - architecture: centralized
+  - morphology: 5_arms_full
+  - arena: default
+  - environment: directed_locomotion
+  - _self_