From c1a1342db2c3bc095ad5eb2617c10d633a162dcc Mon Sep 17 00:00:00 2001
From: dev <dev@local>
Date: Fri, 27 Feb 2026 11:58:42 +0000
Subject: [PATCH] docs: add end-user operation reference

---
 docs/user-guide.md | 131 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 131 insertions(+)
 create mode 100644 docs/user-guide.md

diff --git a/docs/user-guide.md b/docs/user-guide.md
new file mode 100644
index 0000000..24dfcd9
--- /dev/null
+++ b/docs/user-guide.md
@@ -0,0 +1,131 @@
+# User Guide
+
+## Goal
+
+ScanSlicer helps you turn a single scan image (for example, a flatbed scan containing many printed photos) into individual straightened output files.
+
+## Supported Input/Output
+
+- Input directory scan for files ending with: `.png`, `.jpg`, `.jpeg`
+- Output formats:
+  - `jpg` with quality control (`1-100`)
+  - `png` with compression control (`0-9`)
+
+## Main UI Areas
+
+- Left panel:
+  - Directory and image navigation
+  - Save settings
+  - Presets and auto-tune
+  - Detection parameter controls
+- Right panel:
+  - Preview canvas with detected/manual boxes
+  - Toolbar actions (detect, lock, rotate mode, add/remove box, etc.)
+- Bottom status bar:
+  - Current status text
+  - Current filename
+
+## Basic Workflow
+
+1. Click `Open directory`.
+2. Confirm `Output Directory` (or click `Set output directory`).
+3. Select sorting mode (`Name` or `Time`) if needed.
+4. Load an image from the image dropdown, or use previous/next buttons.
+5. Run detection (`Detect`) or rely on automatic detect-on-load.
+6. Review and edit boxes.
+7. Lock the boxes to export.
+8. Click `Save images`.
+
+## Box Editing
+
+### Select and inspect
+
+- Click inside a box to make it active.
+- Active box index is shown in the toolbar (`Active Box: N`).
+
+### Corner drag
+
+- Drag corner handles to reshape the quadrilateral freely.
+
+### Move entire box
+
+- Double-click inside a box, then drag to move it.
+
+### Rotate mode
+
+- Toggle rotate mode (toolbar rotate button).
+- Drag corner handles to rotate the active box.
+
+### Squarize
+
+- Converts active quadrilateral into a cleaner rectangle while preserving tilt.
+- Enables side handles for edge-length adjustment.
+
+### Reset rotation
+
+- Resets active box orientation to axis-aligned while keeping center/size.
+
+### Add/remove
+
+- `Add box`: inserts a new manual box (starts locked).
+- `Remove active box`: deletes current active box.
+
+## Locking Behavior
+
+- Only locked boxes are saved.
+- `Lock/unlock active` toggles one box.
+- `Lock/unlock all` toggles every box currently shown.
+- During new detections, locked boxes are preserved and merged with new candidates (overlap-aware).
+
+## Canvas Navigation
+
+- Right-click drag: pan.
+- Mouse wheel: zoom.
+- `Reset view`: re-fit image to viewport.
+
+## Preview Filter Toggle
+
+- `Filter` shows the processed detection mask preview instead of the original image.
+- This uses cached results from the last detection run.
+
+## Auto-Tune Workflow
+
+1. Choose profile (`Fast`, `Balanced`, `Thorough`, `Exhaustive`).
+2. Click `Auto-tune`.
+3. Auto-tune runs a coarse candidate scan then refines top candidates.
+4. Best parameter set is applied automatically.
+5. Run detection again (handled by app after auto-tune completion).
+
+## Presets and Defaults
+
+- `Load defaults`: load saved defaults if present; else factory defaults.
+- `Save new defaults`: persist current parameters as default.
+- `Save as preset...`: save current parameter set with a name.
+- `Delete current preset`: remove a user preset.
+- Preset dropdown:
+  - `Custom` means unsaved/manual state.
+  - Built-in presets are currently empty; user presets are supported.
+
+## Saving Outputs
+
+- Save filename format:
+  - `<input_basename>_<index>.<ext>`
+  - Example: `scan_003.jpg`
+- Export uses perspective transform per box, so output is straightened to the box geometry.
+- If no locked boxes exist, save is blocked with a warning.
+
+## Status and Logs
+
+- Status messages are shown in the bottom bar.
+- A session log is also written to disk (`status.log` path depends on runtime config).
+
+## Tips
+
+- If no photos are detected:
+  - Try toggling `Preview filter` to inspect mask quality.
+  - Adjust threshold/canny, morphology, and area/aspect controls.
+  - Use `Auto-tune` with a deeper profile.
+- For mixed photo sizes:
+  - Relax `Min Photo Size` and widen aspect ratio bounds.
+- For border artifacts:
+  - Increase `Ignore Border Margin`.