From 9e135ea28c6e8b78edc190f21f422e5c8434a5e1 Mon Sep 17 00:00:00 2001
From: asreva <ivan.sievering@epfl.ch>
Date: Wed, 20 May 2026 16:19:54 +0200
Subject: [PATCH] Improve README clarity and onboarding flow

Add Quick start section, surface uv run throughout, fix repo URL
placeholder, and rename 'How it works' to 'Internals'.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 47 ++++++++++++++++++++++++++++++++---------------
 1 file changed, 32 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 34a201a..57c32b9 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,41 @@
 # River Annotation Tool
 
-A desktop application for manually annotating river video clips as part of the [HydroScan](https://github.com/HydroScan) project. Annotators draw pixel-level water masks over river footage and answer structured survey questions about flow conditions, lighting, and scene quality.
+A desktop GUI application for manually annotating river video clips as part of the [HydroScan](https://github.com/HydroScan) project. Annotators draw pixel-level water masks over river footage and answer structured survey questions about flow conditions, lighting, and scene quality.
 
 ## Requirements
 
 - Python 3.12
 - [uv](https://docs.astral.sh/uv/) (recommended) or pip
 
+## Quick start
+
+```sh
+# 1. Clone and install
+git clone https://github.com/HydroScan/river-annotation-tool
+cd river-annotation-tool
+uv sync
+
+# 2. Create config and clip list from examples
+cp config/config.example.yaml config/config.yaml
+cp config/clips.example.txt config/clips.txt
+
+# 3. Edit config/config.yaml (set data_dir and out_dir)
+#    Edit config/clips.txt (list clips to annotate)
+
+# 4. Run
+uv run python -m river_annotation_tool.annotation_script
+```
+
 ## Installation
 
 ```sh
-# Clone the repository
-git clone <repo-url>
-cd river-annotation-tool
-
 # Install with uv (creates the virtual environment automatically)
 uv sync
 
 # Or with pip
 python -m venv .venv
 .venv\Scripts\activate        # Windows
-# source .venv/bin/activate   # macOS/Linux
+source .venv/bin/activate     # macOS/Linux
 pip install -e .
 ```
 
@@ -33,7 +48,7 @@ cp config/config.example.yaml config/config.yaml
 cp config/clips.example.txt config/clips.txt
 ```
 
-Edit `config/config.yaml` to set your `data_dir` and `out_dir`, then edit `config/clips.txt` to list the clips you want to annotate.
+Edit `config/config.yaml` to set your `data_dir` and `out_dir`, then edit `config/clips.txt` to list the clips you want to annotate. See the [Configuration](#configuration) section for all available options.
 
 ### S3 storage (optional)
 
@@ -65,6 +80,8 @@ The `clips_file` (the list of clip filenames to annotate) is always read from th
 ## Usage
 
 ```sh
+uv run python -m river_annotation_tool.annotation_script
+# or, if you have the venv activated:
 python -m river_annotation_tool.annotation_script
 ```
 
@@ -84,16 +101,16 @@ python -m river_annotation_tool.annotation_script
 
 ```sh
 # Annotate clips listed in config/clips.txt (default)
-python -m river_annotation_tool.annotation_script
+uv run python -m river_annotation_tool.annotation_script
 
 # Use a different config file
-python -m river_annotation_tool.annotation_script --config config/my_config.yaml
+uv run python -m river_annotation_tool.annotation_script --config config/my_config.yaml
 
 # Override paths from the command line
-python -m river_annotation_tool.annotation_script --data data/clips --out data/out
+uv run python -m river_annotation_tool.annotation_script --data data/clips --out data/out
 
 # Annotate a single specific clip
-python -m river_annotation_tool.annotation_script --clip left_20230615T120000
+uv run python -m river_annotation_tool.annotation_script --clip left_20230615T120000
 ```
 
 ## Configuration
@@ -286,7 +303,7 @@ Keys and values are determined by the `questions` section in `config/config.yaml
 }
 ```
 
-## How it works
+## Internals
 
 ### Clip format
 
@@ -333,10 +350,10 @@ pyproject.toml                      # Project metadata and dependencies
 
 ```sh
 # Install pre-commit hooks
-pre-commit install
-pre-commit run --all-files   # Run manually once
+uv run pre-commit install
+uv run pre-commit run --all-files   # Run manually once
 
 # Add a dependency
 uv add <package>
-uv add --dev <package>       # Development-only
+uv add --dev <package>              # Development-only
 ```