From 7fe217de0fe1f46241f4798d2cb2ec587e5e56c3 Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo@depeuter.dev>
Date: Tue, 31 Mar 2026 19:53:45 +0000
Subject: [PATCH] docs: update documentation for logging and configuration

- Add Quick Start guide with installation and configuration steps
- Document unified logging framework features
- Explain configuration management for multiple researchers
- Add project structure overview showing experiment_logger
- Update training examples with new patterns
- Add logging best practices to CONTRIBUTING.md
---
 README.md            | 74 +++++++++++++++++++++++++++++++++++++++++---
 docs/CONTRIBUTING.md |  9 ++++++
 2 files changed, 78 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 47b0552..74b001e 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,81 @@
 # Brittle Star
 
-## Usage
+Reinforcement learning research on brittle star locomotion using PPO.
 
-### UV
+## Quick Start
 
-To set up the UV module, you can run the following command:
+### Installation
+
+Set up the environment using UV:
 
 ```bash
 uv sync --frozen
 ```
 
-example command:
+### Configuration
+
+1. **Copy the default configuration:**
+   ```bash
+   cp configs/default_ppo.yaml configs/my_experiment.yaml
+   ```
+
+2. **Edit `configs/my_experiment.yaml`** to set your WandB credentials:
+   ```yaml
+   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:**
+   ```bash
+   uv run wandb login
+   ```
+
+### Training
+
+Run training with your configuration:
 
 ```bash
-uv run src/train.py --model_name my_model --epochs 50 --batch_size 32
+uv run python src/train.py
 ```
+
+Or use a custom config file:
+
+```bash
+uv run python src/train.py --config configs/my_experiment.yaml
+```
+
+Override specific parameters:
+
+```bash
+uv run python src/train.py --learning-rate 0.001 --num-envs 32 --track
+```
+
+### Logging
+
+The training script uses a unified logging framework that:
+- Logs to **WandB** (when enabled)
+- Saves metrics to **local disk** (JSON files in `runs/`)
+- Displays progress in **stdout**
+
+All experiment data is preserved locally, even if WandB is unavailable.
+
+## Project Structure
+
+```
+src/brittle_star_project/  # Core library (reusable components)
+├── logging/               # Unified logging framework
+├── environment/           # Environment wrappers
+├── rl/                    # RL algorithms and models
+└── dataclasses/          # Configuration dataclasses
+
+configs/                   # Training configurations
+runs/                      # Training outputs (checkpoints, metrics)
+```
+
+## For Researchers
+
+**Important:** Do not commit your personal WandB credentials to the repository. 
+Instead, create your own config file (e.g., `configs/yourname.yaml`) and add it to `.gitignore` if needed.
+
+See [configs/README.md](configs/README.md) for more details on configuration management.
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index efd1399..ee9b4dc 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -33,3 +33,12 @@ Code readability is paramount, as code is read far more frequently than it is wr
 * **Simulation:** The simulation environment utilizes a MuJoCo brittle star. XML MuJoCo structures must remain realistic and respect morphological constraints.
 * **Experiment Tracking:** Weights & Biases (wandb) must be utilized for tracking and logging all experiments.
 * **Code Styling:** All code must conform to the chosen style guide (i.e. Google standard). This is enforced using build tools and pre-commit hooks such as flake8, black, or isort.
+
+## 5. AI-Assisted Development & Code Review
+
+This project supports AI-assisted development to enhance productivity, but contributors must take full responsibility for all AI-generated outputs.
+
+* **Self-Review Requirement:** Contributors must thoroughly self-review all AI-assisted code, documentation, and configurations before requesting peer review. This includes verifying correctness, adherence to project standards, scientific validity, and integration with existing code.
+* **Quality Standards:** AI-generated content must meet the same rigorous standards as manually written code, including proper testing, documentation, and alignment with the scientific methodology outlined in Section 1.
+* **Available Skills:** This project provides specific AI skills for common tasks (located in `.agents/skills/`), including linting and testing workflows. Contributors should leverage these skills to maintain consistency and quality.
+* **Transparency:** When using AI assistance for complex algorithmic decisions or scientific design choices, contributors should document the rationale in commit messages or code comments where appropriate.