diff --git a/README.md b/README.md
index 26a6c57..b7c65b3 100644
--- a/README.md
+++ b/README.md
@@ -3,24 +3,54 @@
[](https://transit_opt.readthedocs.io/en/latest/?version=latest)
-This repo is meant to host code for the joint design of public transport schedules and DRT fleet sizes.
-- For an overview of the research area, check [Planning, operation, and control of bus transport systems: A literature review](https://www.sciencedirect.com/science/article/abs/pii/S0191261515000454)
-- The specific focus of this research is frequency setting problem.
-- We aim to add DRT fleet sizing to the frequency setting problem. A relevant paper that describes the research area is [Joint design of multimodal transit networks and shared autonomous mobility fleets](https://www.sciencedirect.com/science/article/pii/S235214651930016X)
+This repository provides a framework for the joint optimization of public transport schedules and Demand Responsive Transit (DRT) fleet sizes.
-> [!WARNING]
-> This is a WIP research project. You can find a rough overview of functionality in the notebooks folder, but the codebase will change in the next few weeks
+For an overview of the research area, see [Planning, operation, and control of bus transport systems: A literature review](https://www.sciencedirect.com/science/article/abs/pii/S0191261515000454). The specific focus of this implementation is the frequency setting problem, extending it to multimodal networks (PT frequency setting + DRT discrete fleet sizing). A relevant foundational paper is [Joint design of multimodal transit networks and shared autonomous mobility fleets](https://www.sciencedirect.com/science/article/pii/S235214651930016X).
## Features
-- [ ] Read GTFS and convert to matrix for optimisation
-- [ ] Headway optimisation of existing bus network
- - [ ] Different objective functions
- - [ ] Configurable constraints
- - [ ] Algorithms: PSO
-- [ ] Adding DRT fleet sizing to problem
-- [ ] Writing output back to GTFS
+- Encoding
+ - Parse and extract operational data directly from raw GTFS feeds.
+- Optimisation
+ - Headway optimization of existing transit networks using metaheuristics (PSO via PyMOO).
+ - Joint optimization of Fixed-Route PT headways and DRT fleet sizing.
+ - Pluggable framework for customized objective functions (e.g., waiting time, service coverage) and configurable constraints (e.g., fleet limits).
+- Decoding
+ - Automated reconstruction of optimized solutions back into valid GTFS outputs for downstream simulation (e.g., MATSim).
+## Installation
+
+This project uses `uv` for dependency management. To set up the virtual environment:
+
+```bash
+uv venv --python 3.12 .transit_opt_uv
+source .transit_opt_uv/bin/activate
+uv pip install -e .
+uv pip install -r requirements.txt
+```
+
+## Usage
+
+The core functional pipeline runs via the CLI using a YAML configuration file. The configuration defines the input GTFS, the allowable headway parameters, optimization constraints, evaluation intervals, and output directories.
+
+To run the optimization pipeline:
+
+```bash
+python scripts/run.py --config configs/config_template.yaml
+```
+
+If you are running iterative setups (such as starting an optimization run with seeded samples from a previous run), you can specify the target iteration index:
+
+```bash
+python scripts/run.py --config configs/iteration_01/your_config.yaml --iteration 1
+```
+
+### Notebooks
+
+You can find conceptual walk-throughs, data visualisations, and implementation examples in the `notebooks/` directory.
+
+> [!WARNING]
+> While notebooks are a helpful starting point to understand the framework's mechanics, some may be outdated compared to the active `scripts/run.py` pipeline.
## Credits
diff --git a/configs/README.md b/configs/README.md
new file mode 100644
index 0000000..da06eee
--- /dev/null
+++ b/configs/README.md
@@ -0,0 +1,24 @@
+# Config notes
+
+- `config_template.yaml` is the starting point for anyone wanting to run the optimization pipeline.
+
+I use multiple configs to run different scenarios. I have created a naming convention for these configs.
+
+
+### Components
+
+| Element | Description | Example Values | Example Meaning |
+|----------|--------------|----------------|-----------------|
+| **objective** | The optimisation objective being evaluated | `wt` = WaitingTimeObjective
`sc` = StopCoverageObjective | `wt` → objective minimises user waiting time |
+| **time_aggregation** | How values are aggregated across time intervals | `av` = average
`pk` = peak
`sm` = sum
`int` = intervals | `av` → uses average values across intervals |
+| **metric** | The performance measure used in the objective | `tot` = total
`var` = variance
`atk` = atkinson | `tot` → total waiting time or total vehicles
`atk` → evaluates inequality via Atkinson Index |
+
+### Examples
+
+| Config file | Expanded meaning |
+|--------------|------------------|
+| `wt_av_tot.yaml` | WaitingTimeObjective, time aggregation = *average*, metric = *total* |
+| `wt_pk_var.yaml` | WaitingTimeObjective, time aggregation = *peak*, metric = *variance* |
+| `sc_av_var.yaml` | StopCoverageObjective, time aggregation = *average*, metric = *variance* |
+| `sc_int_var.yaml` | StopCoverageObjective, time aggregation = *intervals*, metric = *variance* |
+| `wt_av_atk.yaml` | WaitingTimeObjective, time aggregation = *average*, metric = *atkinson* |