diff --git a/README.md b/README.md
index 0281c8a..a67c67d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,44 @@
-# Raster2SVG-Studio
+# Raster2SVG Studio
+
+A Python tool (CLI + GUI) that converts raster images to SVG using selectable styles.
+Initial styles:
+- Posterized (flat color regions)
+- Line-art (binary edge/ink look)
+
+## Requirements
+- Python 3.10+
+- Qt: PySide6
+- OpenCV: opencv-python
+- NumPy
+- svgwrite
+Optional (for best SVG preview quality in GUI):
+- cairosvg
+
+## Install (editable)
+```bash
+cd raster2svg-studio
+python -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install -e .
+````
+
+## CLI usage
+
+```bash
+r2s convert --in input.jpg --out out.svg --style posterized --params '{"n_colors":6,"min_area":80,"simplify":1.2}'
+r2s convert --in input.jpg --out out.svg --style lineart --params '{"mode":"adaptive","block_size":31,"c":7,"min_area":40,"simplify":1.0}'
+```
+
+## GUI usage
+
+```bash
+r2s gui
+```
+
+## Notes
+
+* SVG preview in the GUI is rendered by converting SVG -> PNG in memory.
+  If `cairosvg` is not installed, the preview falls back to showing the processed raster stage.
+* This scaffold is designed to add a "woodcut" style next (edges + hatching).
 
-A Python tool (CLI + GUI) that converts raster images to SVG using selectable styles.
\ No newline at end of file