docs: add autotune and feedback internals

docs/autotune.md

@@ -0,0 +1,132 @@
+# Auto-Tune and Feedback
+
+## Purpose
+
+Auto-tune searches parameter combinations for the current image and applies the best-performing set automatically.
+
+It is designed to:
+
+- Find usable boxes quickly on difficult scans.
+- Improve ranking using prior saved user outcomes (feedback learning).
+
+## Profiles
+
+Supported profiles:
+
+- `Fast`
+- `Balanced` (default)
+- `Thorough`
+- `Exhaustive`
+
+Each profile controls:
+
+- candidate breadth (`thresholds`, adaptive settings, morphology combinations)
+- runtime limits (`max_candidates_*`, `seed_limit`)
+- convergence limits (`early_stop_*`)
+- refinement depth (`finalists_*`)
+
+Higher profiles evaluate more candidates and typically take longer.
+
+## Candidate Generation
+
+Candidate sets are built from:
+
+- Baseline current parameter values
+- Threshold-based combinations
+- Adaptive threshold combinations
+- Otsu combinations
+- Bounded permutations of bbox/aspect windows
+
+Then candidates are:
+
+1. Deduplicated
+2. Capped by profile runtime limits
+3. Evenly sampled when over limit
+4. Ranked before evaluation
+
+## Candidate Ranking (Pre-Evaluation)
+
+Ranking prefers:
+
+- candidates closer to current parameter values
+- candidates similar to successful feedback entries from visually similar images
+
+Similarity components:
+
+- image feature similarity (`mean`, `std`, `p50`, edge density)
+- normalized parameter distance over each parameter range
+- optional alignment to `expected_count`
+
+## Two-Phase Search
+
+### Coarse pass
+
+- Runs many candidates quickly using:
+  - downscaled image (max dimension 1400)
+  - `fast_mode=True`
+- Uses early-stop when score stagnates and convergence conditions are met.
+
+### Fine pass
+
+- Re-runs only top finalists at full resolution and full detection path.
+- Best final candidate is applied to live parameters.
+
+## Box Scoring Heuristics
+
+Detected box sets are scored by:
+
+- plausible count range
+- multi-photo preference
+- total area coverage
+- uniformity of box area proportions
+- penalty for too many tiny boxes
+- optional `expected_count` alignment bonuses/penalties
+- feedback similarity bonus
+
+If no boxes are found, score is strongly negative.
+
+## Feedback Learning
+
+Feedback is recorded when slices are saved:
+
+- source image path
+- parameter values used
+- image features
+- detected boxes
+- final locked/saved boxes
+- final box signature and count
+- timestamp
+
+Duplicate feedback entries (same image path + final signature) are replaced with latest.
+
+## Feedback File
+
+Default path:
+
+- `~/.config/scanslicer/autotune-feedback.json`
+
+Container path (`/.dockerenv` and `/work` exists):
+
+- `/work/.scanslicer/autotune-feedback.json`
+
+Override:
+
+- `SCANSLICER_FEEDBACK_PATH`
+
+Legacy override names are still accepted for backward compatibility.
+
+Maximum retained entries:
+
+- `500` (latest entries kept)
+
+## Clearing Feedback
+
+UI action `Clear auto-tune history`:
+
+- empties in-memory feedback list
+- removes persisted feedback file if present
+
+## Related Settings
+
+- `expected_count` strongly influences scoring and early-stop decisions.
+- area/aspect parameters can dominate candidate success when scene geometry is constrained.