Add a getting-started guide

A first user hit a wall at the door: the README still said "design only,
no code yet", and nothing anywhere said how to drive the editor.

docs/guide.md walks one PDF to one bundle — install, the five per-page
decisions, markers and jump targets, the title block, export — with a
mouse/key table and the failures that actually happen. The README's stale
status and installation lines go with it.

README.md

@@ -8,7 +8,8 @@ A slice is one *system* — one full line of music across all voices, typically
 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.
+**New here? [docs/guide.md](docs/guide.md) walks you through making your first
+bundle.**
 
 ## How it works
 
@@ -29,20 +30,25 @@ 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.
+needs a system package. LilyPond is optional and only enables re-engraving.
+
+Then:
+
+```
+noteman-slicer edit my-song.pdf
+```
 
 ## Documentation
 
 | | |
 |---|---|
+| [docs/guide.md](docs/guide.md) | How to use it: install, cut a score, place markers, export a bundle. Start here if you just want to make one. |
 | [CONTEXT.md](CONTEXT.md) | Glossary. What a slice, cut, discard, bundle and song scale actually mean here. Start here. |
 | [docs/spec.md](docs/spec.md) | The specification: pipeline, geometry model, detection, editor, bundle format, and what noteman has to change. |
 | [docs/bundle-format.md](docs/bundle-format.md) | The Score Bundle Format — a standalone specification of the export format, independent of this tool. |

docs/guide.md

@@ -0,0 +1,145 @@
+# Making a bundle
+
+Start to finish: a score PDF in, one `.zip` out that noteman can open. Fifteen
+minutes for a typical four-page song, most of it spent nudging cuts.
+
+## Install
+
+```
+uv tool install --editable .
+```
+
+That puts `noteman-slicer` on PATH; it runs from any directory. Everything it
+needs is a wheel — no system packages. LilyPond is optional and only enables
+re-engraving (below); without it the tool works the same minus that pane.
+
+## The one command you need
+
+```
+noteman-slicer edit my-song.pdf
+```
+
+The editor opens on page 1 with detection's guesses already drawn: horizontal
+**cuts** between the systems, a **skew** correction, and a blue **content
+rectangle** marking what is music rather than page margin. All of it is a
+starting point — detection is an accelerator, not an authority. Fix whatever is
+wrong.
+
+Your work is saved to `my-song.slicer.json` next to the PDF, automatically on
+export and with Ctrl+S any time. Closing and reopening picks up where you left
+off.
+
+## What you do on each page
+
+1. **Straighten it.** If the staff lines slope, turn the *Skew* dial until they
+   are level. The preview updates live.
+2. **Fix the cuts.** One cut line per boundary between systems. Double-click to
+   add one, drag to move it, right-click to delete it. A cut is a polyline, not
+   a straight line — Ctrl-click on a cut adds a vertex, so it can bend around a
+   low-hanging lyric or a slur that crosses the gap. Right-click a vertex to
+   drop it.
+3. **Discard what isn't music.** Page headers, footers, page numbers and title
+   blocks are slices too, and they should not reach the tablet. Click the slice,
+   press <kbd>D</kbd>. Discarded slices show hatched. <kbd>D</kbd> again brings
+   one back.
+4. **Set the content rectangle.** Drag the blue edges so they hold the music and
+   nothing else. This is the horizontal crop for every slice on the page.
+5. **Set black and white points.** Pull the *White point* down until the paper
+   goes pure white and its texture disappears; pull *Black point* up until the
+   notes are solid black rather than grey mush. Scans need this; clean digital
+   PDFs usually don't.
+
+Page Up / Page Down move between pages. Levels carry over from the previous
+page, so a consistent scan only needs setting once.
+
+## Markers
+
+Markers are the navigation symbols noteman uses to jump around the score:
+rehearsal letters, section labels, segno, coda, fine, repeats, voltas, and the
+D.S./D.C. instructions. They belong to a slice.
+
+Select the slice, pick the type, type a label if the type takes one (rehearsal
+letters, section labels and voltas do), and press **Add**.
+
+Jump markers — *to coda*, *D.S. al coda*, *D.C. al fine* and friends — also need
+a destination. After adding one, press **Set target…** and click the slice it
+jumps to, on any page. That is what lets noteman follow the repeat structure
+instead of just scrolling.
+
+## The title block
+
+Fill in the *Song* section. **Title is required** — export refuses without one.
+The rest (subtitle, composer, original artist, arranger, lyricist, translator,
+voices) is optional and travels with the bundle into noteman's library.
+
+*Tempo* is beats per minute, a number, because a number can drive a metronome
+and "Andante" cannot.
+
+## Export
+
+**Export bundle…**, choose where the `.zip` goes, done. Inside are the slice
+images in order, their markers, the song metadata, and the original PDF as the
+archive copy. That zip is the whole interface to noteman; hand it over and open
+it there.
+
+Two things worth knowing:
+
+- **Shrink the original PDF…** offers to store the archived PDF as bilevel,
+  which is dramatically smaller for scans. It shows you a before/after crop
+  first — check that the staff lines survived. It never touches the slices.
+- **An exported project is spent.** Reopening the same PDF starts fresh from
+  detection rather than resuming decisions that already shipped. If you really
+  want the old cuts back, `noteman-slicer edit my-song.pdf --resume`.
+
+## Re-engraving a slice (optional, needs LilyPond)
+
+When a system is beyond rescue — a bad scan, a wrong transposition, a passage
+you want rewritten — shift-double-click it. A window opens where you enter the
+music as LilyPond, one block per voice, render, and compare against the
+original. Accept and the rendered version replaces that slice in the bundle.
+
+The LilyPond you typed travels in the bundle alongside the image, so the passage
+can be corrected and re-engraved later, or played, without the project file.
+
+## Mouse and keyboard
+
+| | |
+|---|---|
+| Double-click | add a cut |
+| Drag a cut | move it |
+| Ctrl-click a cut | add a vertex |
+| Right-click | delete the cut or vertex under the cursor |
+| Click a slice, then <kbd>D</kbd> | discard it (or bring it back) |
+| Drag the blue edges | resize the content rectangle |
+| Shift-double-click a slice | re-engrave it |
+| <kbd>Page Up</kbd> / <kbd>Page Down</kbd> | previous / next page |
+| <kbd>Ctrl</kbd>+<kbd>S</kbd> | save the project |
+
+## What the tool won't do
+
+Erasing a previous owner's pencil marks, chord letters and breath marks. Do that
+in GIMP before slicing — with a stylus it is quick, and no amount of thresholding
+substitutes for it.
+
+## When something looks wrong
+
+| | |
+|---|---|
+| Detection found no systems, or one giant one | The score has no bracket joining the staves; add the cuts by hand. |
+| "The PDF has changed since these cuts were made" | The file was edited or replaced under an existing project. The cuts probably no longer line up — re-cut. |
+| Export says a title is required | Fill in *Song → Title*. |
+| Slices look grey and washed out | The white point is too high. |
+| Notes have holes in them | The black point is too high. |
+
+## The command line
+
+The editor is the tool; these exist for checking things quickly.
+
+```
+noteman-slicer info my-song.pdf        # source type and page rasters
+noteman-slicer detect my-song.pdf      # detection results + debug overlays
+noteman-slicer project my-song.pdf     # what the project file currently holds
+noteman-slicer export my-song.pdf      # export without opening the editor
+```
+
+Every command takes `--type raster|vector` to override source-type detection.