commit ecd303322f06247ba767d6b5d85a5ba716264329
Author: Esa Kataja <ekataja@gmail.com>
Date:   Tue Jul 28 21:12:41 2026 +0300

    Initial commit

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2c4cf55
--- /dev/null
+++ b/README.md
@@ -0,0 +1,49 @@
+# noteman-slicer
+
+Turns a score PDF into the ordered slice images [noteman](../noteman) consumes,
+plus the navigation markers that sit on them.
+
+A slice is one *system* — one full line of music across all voices, typically
+4–12 bars with lyrics intact. noteman displays them as a continuous vertical
+scroll, so the slicer's job is to cut a printed page into systems, clean them up
+enough to read on a tablet, and tag them with the score's navigation symbols.
+
+**Status: design only.** No code yet. The design is settled; see below.
+
+## How it works
+
+Open a PDF, and the tool proposes cuts between systems, a skew correction, and a
+content rectangle. You correct all of it — source quality varies too much for
+unattended processing, so detection is an accelerator that nothing depends on
+being right. You mark the header and footer regions discarded, set black and
+white points until the paper disappears and the notes go solid, place the
+rehearsal letters and jump markers, fill in the title block, and export.
+
+Out comes one zip: the slices in order, their markers, the original PDF, and the
+song metadata. That bundle is the only channel to noteman — there's no API
+between the two tools.
+
+Erasing previous-owner pencil marks, chord letters and breath marks stays in
+GIMP. That's the irreducible manual part, and GIMP with a stylus is already good
+at it.
+
+## Installation
+
+Not yet installable. When it is:
+
+```
+uv tool install --editable .
+```
+
+That puts a `noteman-slicer` command on PATH which runs from any directory — no venv to
+activate. Dependencies (PyMuPDF, PySide6, OpenCV, numpy) are all wheels; nothing
+needs a system package.
+
+## Documentation
+
+| | |
+|---|---|
+| [CONTEXT.md](CONTEXT.md) | Glossary. What a slice, cut, discard, bundle and song scale actually mean here. Start here. |
+| [slicer-handoff.md](slicer-handoff.md) | The design: pipeline, geometry model, detection, bundle format, and what noteman has to change. |
+| [docs/adr/0001](docs/adr/0001-slicer-owns-image-processing-bundle-is-the-only-channel.md) | Why the slicer owns all image processing and the bundle is the only channel. |
+| [BACKLOG.md](BACKLOG.md) | Deliberately deferred, with the reasoning that got it deferred. |