diff --git a/README.md b/README.md
new file mode 100644
index 0000000..068256a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,144 @@
+# ScanSlicer
+
+ScanSlicer is a desktop Qt application for extracting multiple photos from a flatbed scan image. It detects photo regions, lets you correct boxes manually, then saves perspective-corrected crops.
+
+## What It Does
+
+- Detects photo boxes from `.png`, `.jpg`, and `.jpeg` source images.
+- Supports threshold-based and Canny-based detection pipelines.
+- Provides manual correction tools (corner drag, edge drag, rotate, move, add/remove box).
+- Saves only locked boxes, each as a perspective-corrected output image.
+- Includes auto-tuning with feedback learning from your prior saved results.
+- Works on Linux desktops over Wayland or X11.
+
+## Requirements
+
+- Python `>=3.10`
+- Linux desktop session (for example KDE Plasma) over Wayland or X11
+- System libraries required by Qt/OpenCV (see `Dockerfile` for a known-good package set)
+
+Project dependencies (from `pyproject.toml`):
+
+- `PySide6`
+- `opencv-python`
+- `numpy`
+- `Pillow`
+
+## Quick Start
+
+### Run with `uv` (recommended for local dev)
+
+```bash
+uv sync --frozen
+uv run scanslicer
+```
+
+Open a specific input directory at launch:
+
+```bash
+uv run scanslicer /path/to/scans
+```
+
+Choose backend explicitly:
+
+```bash
+uv run scanslicer --backend wayland
+uv run scanslicer --backend x11
+```
+
+### Run with Python directly
+
+The package directory now matches the published name:
+
+```bash
+python -m scanslicer
+```
+
+### CLI
+
+```text
+scanslicer [path] [--backend {auto,wayland,x11}]
+```
+
+- `path`: optional startup directory containing scan images.
+- `--backend`: display backend selection. `auto` is default.
+
+## Typical Workflow
+
+1. Open an input directory.
+2. Verify output directory (defaults to the opened input directory).
+3. Click `Detect` (or use auto detection triggered on image load).
+4. Adjust boxes as needed.
+5. Lock boxes you want to export (or use lock-all).
+6. Choose save format (`jpg` or `png`) and quality/compression.
+7. Click `Save images`.
+
+Only locked boxes are exported.
+
+## Runtime Behavior
+
+- Detection and auto-tune run in background worker tasks (`QThreadPool`) so UI stays responsive.
+- Status events are written to a session log file and reflected in the status bar.
+- Detection results are cached (normal and filter preview) to avoid unnecessary re-processing when toggling filter preview.
+
+## Data and Config Files
+
+Default host paths:
+
+- Defaults: `~/.config/scanslicer/defaults.json`
+- Named presets: `~/.config/scanslicer/presets.json`
+- Auto-tune feedback: `~/.config/scanslicer/autotune-feedback.json`
+- Session status log: `~/.config/scanslicer/status.log`
+
+Container behavior:
+
+- When running in container and `/work` exists, these are stored under `/work/.scanslicer/`.
+
+Environment variable overrides:
+
+- `SCANSLICER_DEFAULTS_PATH`
+- `SCANSLICER_PRESETS_PATH`
+- `SCANSLICER_FEEDBACK_PATH`
+- `SCANSLICER_STATUS_LOG_PATH`
+
+Legacy override names are still accepted for backward compatibility.
+
+## Docker Compose
+
+The repo includes a GUI-oriented compose setup for Linux desktop use:
+
+```bash
+docker compose up --build
+```
+
+See `.env.example` and `docker-compose.yml` for required host UID/GID and Wayland/XDG settings.
+
+## AppImage Build
+
+AppImage build scripts and recipe are in `packaging/appimage/`.
+
+- Local: `bash packaging/appimage/build-appimage.sh`
+- Dockerized build: `bash packaging/appimage/build-appimage-docker.sh`
+
+Detailed instructions: `docs/appimage.md`.
+
+## Documentation
+
+- `docs/README.md` - documentation index
+- `docs/user-guide.md` - end-user operation guide
+- `docs/architecture.md` - code architecture and execution flow
+- `docs/parameters.md` - full detection parameter reference
+- `docs/autotune.md` - auto-tune and feedback internals
+- `docs/runtime-config.md` - backend/environment and persistence paths
+- `docs/appimage.md` - AppImage packaging details
+- `docs/development.md` - contributor-focused architecture/workflow notes
+
+## Repository Layout
+
+```text
+scanslicer/                  Application source (UI, controllers, canvas, detection)
+packaging/appimage/           AppImage recipe and build scripts
+Dockerfile                    Runtime image
+docker-compose.yml            GUI container runtime wiring
+pyproject.toml                Python package metadata and dependencies
+```