Add unified_pipeline: merged signature-verification synthetic document generator (part 15)

.gitattributes

@@ -4974,3 +4974,74 @@ unified_pipeline/data/raw/signet/train/059_forg/03_0104059.PNG filter=lfs diff=l
 unified_pipeline/data/raw/signet/train/059_forg/03_0125059.PNG filter=lfs diff=lfs merge=lfs -text
 unified_pipeline/data/raw/signet/train/059_forg/04_0104059.PNG filter=lfs diff=lfs merge=lfs -text
 unified_pipeline/data/raw/signet/train/059_forg/04_0125059.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/060_forg/01_0111060.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/060_forg/01_0121060.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/060_forg/01_0126060.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/060_forg/02_0111060.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/060_forg/02_0121060.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/060_forg/02_0126060.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/060_forg/03_0111060.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/060_forg/03_0121060.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/060_forg/03_0126060.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/060_forg/04_0111060.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/060_forg/04_0121060.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/060_forg/04_0126060.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/062_forg/01_0116062.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/062_forg/01_0201062.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/062_forg/02_0116062.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/062_forg/02_0201062.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/062_forg/03_0109062.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/062_forg/03_0116062.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/062_forg/03_0201062.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/062_forg/04_0109062.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/062_forg/04_0116062.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/062_forg/04_0201062.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/063_forg/01_0104063.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/063_forg/01_0119063.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/063_forg/02_0104063.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/063_forg/02_0119063.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/063_forg/03_0104063.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/063_forg/04_0104063.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/064_forg/01_0105064.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/064_forg/01_0203064.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/064_forg/02_0105064.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/064_forg/02_0203064.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/064_forg/03_0105064.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/064_forg/03_0203064.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/064_forg/04_0105064.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/064_forg/04_0203064.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/065_forg/01_0118065.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/065_forg/01_0206065.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/065_forg/02_0118065.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/065_forg/03_0118065.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/065_forg/03_0206065.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/065_forg/04_0118065.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/065_forg/04_0206065.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/066_forg/01_0212066.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/066_forg/02_0212066.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/066_forg/03_0101066.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/066_forg/03_0212066.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/066_forg/04_0212066.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/067_forg/01_0205067.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/067_forg/01_0212067.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/067_forg/02_0205067.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/067_forg/02_0212067.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/067_forg/03_0205067.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/067_forg/03_0212067.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/067_forg/04_0205067.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/067_forg/04_0212067.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/068_forg/03_0113068.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/068_forg/04_0113068.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/069_forg/01_0106069.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/069_forg/01_0108069.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/069_forg/01_0111069.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/069_forg/02_0106069.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/069_forg/02_0108069.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/069_forg/02_0111069.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/069_forg/03_0106069.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/069_forg/03_0108069.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/069_forg/03_0111069.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/069_forg/04_0106069.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/069_forg/04_0108069.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/data/raw/signet/train/069_forg/04_0111069.PNG filter=lfs diff=lfs merge=lfs -text
+unified_pipeline/docs/unified_pipeline_Metrics_Thresholds_Formulas.pptx filter=lfs diff=lfs merge=lfs -text

unified_pipeline/README.md

@@ -0,0 +1,844 @@
+# unified_pipeline
+
+A single, self-contained synthetic signed-bank-document generator, built
+against a spec deck (`Metrics_Thresholds_Formulas` /
+`Synthetic_Test_Data_Combined.pptx`). It combines two template families --
+9 real scanned bank-document photographs with hand-measured signature-box
+annotations, and 15 procedurally (matplotlib-)drawn documents with
+cosmetic-field realism (SWIFT/NRIC/UEN/amounts) -- behind one config-driven
+(Pydantic + YAML) generation engine, a 12-case-type reject-code taxonomy,
+a shared signature dataset pool (CEDAR, SigNet, BHSig260 Hindi/Bengali), a
+richer Albumentations-backed augmentation set, and a 119-test pytest suite.
+
+**Start here if you're reviewing this:** `data/showcase_dataset/` -- 24
+pre-generated cases covering all 12 case types, each rendered once on a
+scanned template and once on a procedural template, with
+`SHOWCASE_INDEX.csv` as a one-page overview, a `before_after/` folder
+holding every case's metrics preview grouped together (see "Before/after
+degradation preview" below), and `reference_signers_index.json` mapping
+every name/role that appears in the dataset back to their signer identity
+and reference signature image(s) (see "Reference-signer index" below). No
+need to run anything to see what the pipeline produces.
+`docs/unified_pipeline_Metrics_Thresholds_Formulas.pptx` walks through the
+same metrics/thresholds/formulas with worked examples and images.
+
+## This repo is fully self-contained
+
+**Nothing here points outside this folder.** Unzip it anywhere and
+`python main.py` / `pytest` just work -- no sibling checkouts, no external
+dataset downloads. See "Datasets" below for exactly what's bundled and what
+was left out (and why).
+
+## Design notes
+
+A few structural choices worth calling out up front:
+
+- **Per-case output folders** (`case_NNN.../`) hold the rendered document,
+  the exact reference signature used (copied in, not just referenced by
+  path), and the ground truth together -- a flat `sample_NNNNNN.png/.json`
+  layout only makes sense at ML-training scale where nobody opens
+  individual cases; for a reviewed dataset, self-contained per-case folders
+  are the better fit.
+- **Ground-truth schema** is deep and fully populated (geometry/placement/
+  rendering/augmentation audit trail), with top-level convenience fields
+  (`case_id`, `expected_verdict`, `expected_reject_code`) layered on top --
+  so a reader doesn't need to know the nested `verification.verdict` shape
+  to answer "what should a verifier conclude here."
+- **Case generation** runs off one data table (`CASE_TABLE`) plus one
+  generic engine, rather than 12 separate hardcoded functions duplicating
+  the same logic.
+- **Config system** is Pydantic + YAML (validated, typed) -- catches bad
+  values before a long batch run fails partway through.
+- **Templates** are two genuinely complementary families (9 real scanned
+  photos, 15 programmatically-drawn documents) kept separate but unified
+  under one id space. `template_provider: both` is the **default** (see
+  "Template providers" below), so a plain `python main.py` shows both.
+- **Difficulty formula** is identical across both template families --
+  same weights/tiers/normalization; only the *reference constants* differ
+  (see "Difficulty calibration profiles"), and that's a config choice, not
+  a code fork.
+- **Difficulty CLI** takes a specific numeric target (`--target-difficulty
+  0.55`), not a coarse tier, since the score itself is already continuous.
+  See "Difficulty-score targeting" below.
+
+## Datasets ("use all the dataset")
+
+`SignatureDataset` (`src/signatures/signature_dataset.py`) indexes every
+source into one pool under `data/raw/`, each record tagged with
+`source_type` (genuine/forged) and `script` (latin/hindi/bengali):
+
+| Source | Path | Signer group prefix | Bundled | Notes |
+|---|---|---|---|---|
+| CEDAR | `data/raw/cedar/{genuine,forged}` | `signer_NNNN` | Full (1320 + 1320) | Used for the scanned templates. |
+| SigNet | `data/raw/signet/{train,test}` | `signet_NNNN` | Full (2149 files) | Primary Latin-script source. |
+| BHSig260-Hindi | `data/raw/bhsig260_hindi` | `bhsig260_hindi_NNNN` | Capped 8 genuine + 8 forged / writer, 160 writers (2560 files; full archive is ~8600 files / 2.3GB) | |
+| BHSig260-Bengali | `data/raw/bhsig260_bengali` | `bhsig260_bengali_NNNN` | Capped 8+8 / writer, 100 writers (1600 files; full archive is ~5400 files / 1.5GB) | |
+| GPDS | -- | `gpds_NNNN` | **Not bundled** | Never wired into the live generation path (present in the original dataset archive, never validated). `SignatureDataset` still supports it (`gpds_dir` config) if you have the archive and want to point at it. |
+
+**Dropped: an 11-file named-signer demo overlay** (`dataset/hindi_bengali/`
++ `metadata.csv`, mapping a handful of files to hand-picked names like
+"Priya Sharma"). It added no signature diversity beyond what BHSig260
+already provides at ~260x the scale (260 writers vs. 7) -- its only effect
+was a few ground-truth JSONs showing a real name instead of an
+auto-generated one. `SignatureDataset`'s `metadata.csv` support itself is
+still fully functional generic code (see `test_metadata_csv_overrides_signer_identity_and_script`
+in `tests/test_discovery.py`), just not exercised by bundled data anymore.
+
+Total bundled dataset: **~1.7GB**. Any source can be omitted by pointing
+its config path at a location that doesn't exist -- `SignatureDataset`
+skips missing sources gracefully rather than failing (this is how GPDS
+support stays in the code without being bundled).
+
+## Output structure
+
+Every generated case gets its own folder:
+
+```
+output/case_000001/
+    case_000001_document.png              # the rendered document
+    case_000001_reference_signature.png   # copy of the exact signature image used
+    case_000001_companion_signature.png   # (case types that officially test a 2nd signer)
+    case_000001_<box_id>_signature.png    # (any OTHER box on a multi-box template -- see below)
+    case_000001_visualization.png         # (--save-visualization: geometry/metrics overlay)
+    case_000001_ground_truth.json         # full metadata
+output/before_after/
+    case_000001_before_after.png          # (--save-before-after: clean vs. final side by side)
+    case_000002_before_after.png          # grouped in one folder, not scattered per-case --
+    ...                                    # easier to flip through in a row
+output/dataset_summary.csv                # one row per case: template/type/verdict/difficulty
+output/generation_summary.json            # batch totals
+output/resolved_config.yaml               # the fully-resolved config that produced this run
+```
+
+Case-type batches (`quality.case_type` set) get `_<type>` appended to the
+folder name, e.g. `case_000001_3b/`.
+
+**Every signature box on a multi-box template gets signed, always.** If a
+template has more than one signature box but the sample's case type doesn't
+officially test the extra one (e.g. `1a`/`2a`/generic samples on a 2-box
+template), that box still gets filled with its own correct, genuine
+signature rather than being left blank with no explanation -- tracked in
+`metadata["additional_signatures"]`. This never overrides a case type's own
+deliberate blank/wrong target (a `2a` case's target box still correctly
+stays blank with `NO_SIGNATURE`; only its *unrelated* second box gets the
+extra fill). See "Multi-signature-box logic, audited" below.
+
+## Template providers ("works with both template approaches")
+
+Set via `paths.template_provider` in config or `--set paths.template_provider=...`:
+
+- `both` (**default**) -- both pools merged into one id space (`bank_doc_*` + `proc_doc_*`), so a plain `python main.py` shows both template families.
+- `scanned` -- the 9 real scanned bank-document images only.
+- `procedural` -- the 15 matplotlib-drawn documents only (`proc_doc_01`..`proc_doc_15`).
+
+`paths.excluded_template_ids` (default `[]`) can pull any scanned template
+out of the pool without touching the source image file -- exclusion is
+id-stable (doesn't renumber/shift any other template's id).
+
+Every ground-truth JSON records `template_kind` (`"scanned"` / `"procedural"`)
+at the top level regardless of mode.
+
+Both families live under one `templates/` folder:
+
+```
+templates/
+    scanned/
+        guarantee/    bank_doc_01.png, bank_doc_02.png, bank_doc_03.png
+        loan_forms/   bank_doc_04.png, bank_doc_05.png, bank_doc_06.png
+        mandate/      bank_doc_07.png, bank_doc_08.png, bank_doc_09.png
+    procedural/       proc_doc_01.png .. proc_doc_15.png
+```
+
+`templates/scanned/` holds the 9 real scanned photographs (`paths.image_dir`);
+`templates/procedural/` holds the 15 procedurally-drawn documents, rendered
+once and cached as PNGs the same way a scanned template is a fixed image
+(`paths.cache_dir`) -- delete it and it's regenerated automatically on the
+next run, from the drawing code in `src/templates/procedural_template_provider.py`.
+
+## Difficulty calibration profiles
+
+Real signature ink occupies a different proportion of the page on the two
+template families, so procedural samples use different smallness/faintness/
+low_texture reference constants (`smallness_reference_area_ratio=0.003`,
+`faintness_dark_ref=165`, `faintness_light_ref=220`,
+`low_texture_reference_stddev=46` -- see
+`src/config/schema.py::DifficultyWeights`) than scanned samples, which keep
+the spec deck's literal generic values (`0.04` / `90` / `210` / `60`) --
+still an accurate fit for scanned templates' own measured population.
+
+`faintness_dark_ref` and `low_texture_reference_stddev` were refit
+2026-08-11 against a fresh 60-sample natural draw of real procedural output.
+The prior `faintness_dark_ref` (184) sat *above* the real median
+`mean_dark_intensity` (180.6), which floored `faintness` to exactly `0.000`
+for every sample measured -- a 20%-weighted component contributing nothing,
+discriminating nothing, for the whole procedural family. Re-anchored to the
+real 10th percentile (~164, rounded to 165): median sample faintness is now
+~0.29, only the darkest ~13% floor to 0, spread runs to ~0.79 for the
+lightest observed ink. `low_texture_reference_stddev` had never been split
+from the deck-literal default at all, despite the same underlying asymmetry
+existing there too (procedural's vector-rendered ink is naturally less
+textured than scanned's real-photograph ink) -- anchored to the real 90th
+percentile `gray_stddev` (~46.5, rounded to 46), the same treatment already
+given to `smallness_reference_area_ratio`. Verified: re-measured 60 fresh
+procedural samples post-fix -- faintness floors to 0 for only 8/60 (was
+60/60), low_texture floors to 0 for only 7/60; full 119-test suite still
+passes.
+
+This is applied automatically, **per sample**, by `GeneratorContext`
+(`src/generator.py::_difficulty_analyzer_for()`), keyed on each sample's own
+`template_kind()` -- not a config profile you have to remember to select.
+Previously this only applied if the whole run used
+`--config configs/procedural_templates.yaml`, which meant `template_provider:
+both` (or the plain CLI default) silently scored every procedural sample
+against the deck-literal, too-aggressive constants regardless. Fixed: each
+sample now gets the constants that actually fit its template family, even
+within a mixed `both` batch.
+
+If you explicitly set any of the 3 reference constants yourself -- a CLI
+`--set difficulty.smallness_reference_area_ratio=...` override, or a whole
+profile like `configs/procedural_templates.yaml` that sets them itself --
+that choice is respected as-is and applied to every sample regardless of
+template kind; the automatic per-kind default only fills in fields you
+didn't already decide for yourself
+(`DifficultyWeights.model_fields_set` is how this is detected).
+
+## Placement calibration
+
+Signatures are also pasted at a different scale per template family, same
+per-sample-keyed pattern as difficulty calibration above
+(`GeneratorContext._placement_engine_for()`):
+
+- **`min_signature_height_px`**: `24px -> 28px` (shared default -- see
+  `src/config/schema.py::PlacementConfig`, moved off a `placement_engine.py`
+  module constant so it's config-overridable like every other placement
+  knob). Measured 2026-08-11 across 20 real placements per candidate into a
+  genuine 18px "sign here" line: 24px -> 15.1% fully-opaque ink, 28px ->
+  16.8%, with a modest overflow cost (median 4% at 28px vs. 0% at 24px);
+  32px was tested and rejected (20%+ median overflow -- escalates much
+  faster than the legibility gain).
+- **`placement.scale_factor`**: `1.15` (procedural only; scanned keeps the
+  shipped `{min: 0.78, max: 0.95}` range unchanged). Procedural's boxes
+  (200x80px) have real headroom scanned's cramped real "sign here" lines
+  don't -- 1.1 already gave a meaningful legibility gain (opaque-ink
+  fraction 0.238 -> 0.280) with zero overflow; 1.3 starts trading further
+  gains for real overflow (6-7%). Scanned was tested too (0.9 through 1.2)
+  and showed **no change at all** in that range -- `min_signature_height_px`
+  is the actual binding constraint there, not `scale_factor`, so bumping
+  scanned's scale_factor would have been a no-op.
+
+**A real bug surfaced while implementing this**: the difficulty-calibration
+pattern detects genuine user overrides via `model_fields_set`, which works
+because `configs/default.yaml` never explicitly sets the difficulty
+reference constants. It does explicitly set `placement.scale_factor`
+though (to its own baseline range) -- so applying the same pattern
+unmodified would have silently defeated this recalibration on every single
+run, with or without a real override. Fixed by comparing the resolved
+value against the known shipped baseline directly instead of relying on
+field-presence tracking.
+
+Pasting bigger also organically fixed a gap flagged in the earlier
+recalibration work: `smallness_reference_area_ratio=0.003` previously sat
+above even the best 10% of real procedural samples (floor ~0.4, never
+reaching 0). Re-measured post-placement-fix: real median
+`signature_area_ratio` moved 0.00095 -> 0.00180, and `smallness` now
+resolves with genuine spread on its own (8/50 samples reach 0, median
+0.398) -- no further change to the reference constant was needed.
+
+## Difficulty-score targeting
+
+```bash
+python main.py --count 5 --target-difficulty 0.55
+python main.py --count 5 --target-difficulty 0.55 --difficulty-tolerance 0.03 --difficulty-max-attempts 8
+```
+
+A retry-loop (`case_generation.py::generate_case_at_difficulty()`) built on
+this pipeline's own CLI conventions (argparse, `--set key=value`):
+since the difficulty score is already a continuous `[0, 1]` value (not a
+bucket), you ask for a specific number (`0.55`), not a tier. Retries (`--difficulty-max-attempts`, default 5) with fresh but
+still fully deterministic randomness (`seed_manager.python_rng` derived
+from `f"{sample_index}_difficulty_retry{attempt}"`) until the score lands
+within `--difficulty-tolerance` (default 0.05) of the target; if no
+attempt matches, the closest one is kept and `ground_truth.json`'s
+`difficulty_targeting.matched` is `false` so this is never silently
+misreported. See `GeneratorContext.run_sample_targeting_difficulty()`.
+
+## Before/after degradation preview
+
+```bash
+python main.py --count 5 --save-before-after
+```
+
+Builds a clean-vs-final side-by-side comparison combined with a metrics
+overlay into one image. Writes
+`before_after/<case_id>_before_after.png` per sample -- grouped in one
+shared folder rather than scattered one per case folder, so every sample's
+preview can be flipped through in a row without opening each case folder
+individually:
+
+- **BEFORE (left)** -- the clean render (signature placed, before any
+  document-level augmentation), annotated with the "what was actually
+  measured" overlay: the target box (red), the actual
+  signature bbox (yellow), its detected ink polygon (green), and any
+  cosmetic field boxes (cyan = actual, orange = target cell), plus a
+  legend, a **difficulty breakdown** (`value x weight = contribution` per
+  component, e.g. `misplacement: 0.464 x 0.35 = 0.162`), and an
+  **augmentation-applied** panel listing every effect this sample rolled --
+  ON with its strength, or off.
+- **AFTER (right)** -- the final look, labeled with a one-line summary of
+  which effects actually fired (`"AFTER - 2 effect(s): contrast,
+  scanner_noise"`).
+
+Every case in `data/showcase_dataset/` has one of these pre-generated.
+Distinct from the existing `--save-visualization` (a single matplotlib-based
+multi-panel figure -- crop, ink mask, bar chart -- on the FINAL image only,
+no before/after comparison); the two can be used together. See
+`src/visualization/before_after_preview.py`.
+
+## Cosmetic (non-scored) fields
+
+`document.enable_cosmetic_fields: true` (**on by default**) fills in
+name/company-name and, on procedural templates, the fuller SWIFT/NRIC/UEN/
+amount set too -- never read by `DifficultyAnalyzer` or any scored metric.
+
+- **Procedural templates**: full field set at exact coordinates (known
+  from the drawing spec) -- see `src/cosmetics/cosmetic_fields.py`.
+- **Scanned templates**: a best-effort name/company-name field on 7 of the
+  9 templates, found via the same CV line-detection technique already used
+  for signature-box auto-detection (search a hand-picked region for the
+  blank line/table-cell, draw text against it) -- see
+  `src/cosmetics/scanned_cosmetic_fields.py`. `bank_doc_01`/`bank_doc_02`
+  are stock photos with fabricated content already baked into the image
+  (bracketed `[PLACEHOLDER ...]` text, or an already-fully-filled specimen
+  letter) and are left as-is -- there's no genuine blank field to fill
+  without inpainting over existing print.
+
+## Template exclusion (mechanism exists, nothing excluded by default)
+
+`paths.excluded_template_ids` (config list, default `[]`) can pull a
+scanned template out of the pool without touching the source image file --
+exclusion is id-stable (`TemplateLoader(excluded_ids=...)`), so pulling one
+id never renumbers/shifts any other template's id. Every discovered
+template is included by default.
+
+## Scanned cosmetic fields: field semantics, not just position
+
+`bank_doc_09`'s "Company Name" table cell (under `ENTITY DETAILS`, next to
+`Registration Number`) was pasting the *signer's own personal name* into
+it (e.g. "Nancy Ivanov" under a column literally headed "Company Name") --
+the position was correct, but the wrong *kind* of text. Every other
+scanned field really is a personal-name field ("Print Name:", "Name of
+Account Holder:", "Mr./Ms. ___") and correctly gets the signer's name;
+`company_name` is the one exception and now generates an actual company
+name (`generate_company_name()`, seeded, same generator procedural
+templates already used) instead. See `src/cosmetics/scanned_cosmetic_fields.py`'s
+`_GENERATED_FIELD_TEXT` dispatch table.
+
+### Cosmetic-field coordinates are pre-measured and cached, like signature boxes
+
+`signature_boxes` in `annotations/<template_id>.json` have always been
+hand-measured once and just read at generation time -- no per-sample image
+analysis. Cosmetic-field coordinates (where the "Name"/"Company Name" text
+gets drawn on a scanned template) now work exactly the same way, via a new
+`cosmetic_fields` array on the same annotation file:
+
+```json
+"cosmetic_fields": [
+  {"field": "company_name", "mode": "below_line", "line_x": 74, "line_y": 164, "line_w": 303}
+]
+```
+
+**How each coordinate is measured** (`scripts/detect_cosmetic_field_coordinates.py`):
+
+1. A generous *search region* is hand-picked per field, once, by eye (a
+   `(x0, y0, x1, y1)` rectangle expressed as fractions of the page's
+   width/height -- see `FIELD_REGION_RECIPES` in that script). This step
+   only needs to be roughly right, not precise.
+2. Within that region, the *same* classical-CV horizontal-line detector
+   already used to auto-detect signature boxes when no manual annotation
+   exists (`src/templates/box_detector.py`: binarize, morphological
+   opening with a wide horizontal kernel to isolate long thin dark runs,
+   merge nearby fragments) finds the actual blank underline or table
+   row-divider pixel-exactly. Deterministic given the same image, so it
+   only ever needs to run once per template.
+3. The result (`field`, `above_line`/`below_line` mode, and the detected
+   line's exact `x`/`y`/`width`) is written into the template's
+   `annotations/<id>.json`, alongside `signature_boxes`.
+
+Run it manually (`python scripts/detect_cosmetic_field_coordinates.py
+[--force]`) after adding a new scanned template or if a template image
+changes -- it is **not** run as part of normal generation. At generation
+time, `fill_scanned_cosmetic_fields()` (`src/cosmetics/scanned_cosmetic_fields.py`)
+just reads `template.annotation.pages[N].cosmetic_fields` directly, the
+same way signature-box placement already reads `signature_boxes` -- one
+measurement, reused on every sample, instead of re-running CV detection
+per call.
+
+### One "Print Name:" field per signatory, not one per template
+
+`bank_doc_03`, `04`, `05`, `06`, and `08` each have **two** signature
+boxes, and (confirmed by visually cropping every candidate line in each
+template) each box's signatory has their *own* "Print Name:"-style line --
+not one field shared by both parties. The original single-field-per-template
+recipe only ever measured one of the two, so the second signatory's name
+was always left blank regardless of what filled the first. Each field now
+carries an optional `box_id`, tying it to the `signature_boxes[].id` whose
+signer's name belongs on that line:
+
+```json
+"cosmetic_fields": [
+  {"field": "name_sig1", "mode": "above_line", "line_x": 606, "line_y": 464, "line_w": 136, "box_id": "sig1"},
+  {"field": "name_sig2", "mode": "above_line", "line_x": 828, "line_y": 464, "line_w": 136, "box_id": "sig2"}
+]
+```
+
+Fields with no `box_id` (e.g. `bank_doc_09`'s `company_name`) are
+entity-level, not tied to one signer, and are unaffected.
+
+Because a companion/additional signer's identity usually isn't resolved
+until *after* the primary box's cosmetic fields are already filled (see
+`_run_case_sample`/`_run_generic_sample` in `src/generator.py`),
+`_maybe_fill_cosmetic_fields()` only ever fills fields with no `box_id` or
+tied to the box it's given; a second pass, `_fill_box_cosmetic_field()`,
+fills the companion/extra box's own field once that signer's display name
+is known -- so both parties' names land on their own lines, matching
+whichever signature actually got pasted into their box.
+
+While narrowing `bank_doc_03`'s search region to find its second field, a
+related pre-existing bug surfaced: its *first* field had been landing on
+the "By:" line instead of "Print Name:" (both lines sit in the same
+generous search region, and `_find_line_in_region()`'s "pick the widest
+line" heuristic happened to prefer "By:"). Fixed by narrowing that
+template's region to the exact "Print Name:" line's y-band.
+
+## Legible ink on short signature lines
+
+A real "sign here" line on a scanned bank form is often only ~15-25px tall
+at this pipeline's working resolution (e.g. `bank_doc_08`'s "Signature of
+Bank Manager:" line is 22px tall) -- placing a signature stamp from a
+typical few-hundred-pixel-tall dataset source crop into a box that short
+forces a large downscale, sometimes 10-20x. `cv2.resize`'s `INTER_AREA`
+area-averages a multi-pixel-wide source stroke down into a sub-pixel-wide
+destination stroke, which is the geometrically correct way to downscale --
+but it also dilutes that stroke's alpha well below fully opaque across most
+of its footprint. A signature that was solidly inked in its source crop
+could come out mostly under 30-40% opacity: a faint gray smudge rather than
+a smaller-but-still-dark signature (real signatures squeezed onto a short
+line stay dark, just compact).
+
+`PlacementEngine.place()` (`src/placement/placement_engine.py`) now applies
+a gamma correction to the placed alpha channel after any real downscale --
+every partially-transparent pixel gets boosted non-linearly (alpha^gamma,
+gamma<1), which is what actually restores legibility (a plain linear
+rescale matching the *source's own* percentile was tried first and wasn't
+enough: even the source crop's own mid-tone pixels are already somewhat
+soft/anti-aliased from the original scan). Gamma self-scales with
+`final_scale` (the actual resize factor) -- a sample that barely shrank
+gets ~no correction (gamma near 1, alpha^1 = alpha); one squeezed 10-20x
+onto a short line gets the strongest correction (gamma floor 0.18).
+Applied to alpha only, never RGB, so ink *color* is unaffected -- this
+makes thin/faint strokes fully opaque sooner, not darker in hue. Regression
+test: `test_aggressive_downscale_onto_a_short_box_keeps_ink_dark` in
+`tests/test_placement_engine.py`.
+
+## Post-render ink detection: not fooled by the template's own printed content
+
+`GeometryAnalyzer` (`src/analysis/geometry_analyzer.py`) redetects each
+sample's signature from the rendered pixels alone (deliberately -- a real
+verifier only ever sees the final scanned document, not ground-truth
+placement coordinates). Four contamination sources were found and fixed
+across three review passes -- the first two via a user-reported case
+(`bank_doc_08`'s Bank Manager signature, a genuine PASS, whose metrics
+preview showed a bounding box/polygon spanning almost the entire printed
+line instead of just the ink), the third via a broader anomaly scan across
+the whole showcase dataset after a follow-up "the metrics still look kinda
+off" report, the fourth via the interactive UI's degradation lever
+surfacing a sample that visually looked heavily degraded yet scored "easy":
+
+1. **The printed "sign here" rule line itself.** A pasted signature very
+   often sits directly on top of, and touches, that line -- 8-connectivity
+   then merges the line and the ink into ONE component, whose bounding box
+   spans the line's full width. `_strip_printed_rule_line_pixels()` runs a
+   *narrow, absolute-width* (20px, not proportional to the crop -- a
+   signature crossing the middle of the line splits it into two shorter
+   sub-segments, and a proportional kernel could exceed either half's
+   length) horizontal morphological opening to isolate straight
+   single-row runs, then only subtracts ones whose overall connected-component
+   height stays <=3px (so a genuinely tall block of ink -- thick
+   handwriting, or a filled test fixture -- survives; only truly thin,
+   line-like structures get erased).
+2. **Printed field labels near the box** (e.g. "Bank Manager:"). A tight
+   detection pass expands slightly past the annotated box edge, and on a
+   short box that expansion can reach into adjacent label text. Fixed by
+   optionally diffing against the clean, unsigned template image
+   (`analyze(..., baseline_image_rgb=...)`) -- pixels already dark in the
+   baseline (permanent printed content) are never counted as new ink. The
+   baseline is known in advance the same way a real production pipeline
+   knows its own form layouts, not this run's specific signature
+   placement, so this isn't using ground truth the way a real verifier
+   couldn't. Originally skipped automatically when the sample underwent a
+   page-level geometric transform (`perspective`/`page_tilt`/`crumple`)
+   that would misalign a pixel-for-pixel diff -- see contamination source
+   4 below for why that gap itself needed fixing.
+
+Net effect on the reported case: `box_coverage_pct` dropped from a
+contamination-inflated 56% to an accurate ~10%, and the detected polygon
+now tightly traces just the actual ink.
+
+3. **A printed caption below a deliberately BLANK target box** (2a/5a case
+   types -- `_BLANK_CASE_TYPES`). The widened retry pass (`analyze()`'s
+   second, more generous search) exists to chase a signature that was
+   deliberately misplaced far from its own box -- but a 2a/5a target box
+   has no signature at all, so there's nothing to chase, and on a sample
+   where `baseline_image_rgb` had to be omitted (a geometric transform was
+   applied, so a pixel diff would misalign), the widened search had no
+   baseline to exclude already-printed content with. Caught a printed
+   role-caption ("1. SIGNATURE: AUTHORIZED REPRESENTATIVE *") sitting just
+   below the blank box and reported it as a wildly-misplaced signature
+   (`distance_from_box_center_px` ~90-130px, `margin_utilization` >2).
+   Fixed with `analyze(..., expect_blank=True)`, passed whenever the
+   caller already knows from ground truth that this target has no
+   signature (`target_rgba is None` in `_run_case_sample`) -- skips the
+   widened retry entirely, so a genuinely blank box just reports
+   `detected: false` and zeroed metrics, exactly as it should.
+
+4. **Whole blocks of printed text, whenever `perspective`/`page_tilt`/
+   `crumple` actually fired.** Found via the interactive UI's degradation
+   lever: a heavily rotated/noisy "Explore from clean" preview scored
+   16% ("easy") despite looking obviously harder to read than the clean
+   original (48%, "medium"). Root cause: contamination source 2's
+   baseline-diff exclusion was skipped entirely whenever a geometric
+   transform fired (a rotated page no longer lines up pixel-for-pixel with
+   the un-rotated baseline template), so the ONLY defense against printed
+   content near the box was gone -- and `_strip_printed_rule_line_pixels()`
+   only catches thin rule *lines*, not printed paragraph *text*. On one
+   measured sample, a `page_tilt` of well under 1 degree was enough for a
+   nearby paragraph heading to rotate into the search box's expanded
+   region and get counted wholesale as "ink": detected pixels jumped from
+   545 (the real signature) to 13,993, `mean_dark_intensity` dropped from
+   175 to 107 (consistent with picking up dense black print), and the
+   artificially large, well-centered "blob" read as LESS misplaced and
+   LESS small than the real, small, genuine signature -- the opposite of
+   what a harder-to-read page should score. Fixed at the source instead of
+   working around it: `AugmentationEngine.apply_to_document()` now accepts
+   an optional `baseline_image`, and whenever perspective/page_tilt/crumple
+   actually apply, the identical transform (same warp matrix / same
+   `map_x`,`map_y` remap field) is also applied to the baseline companion
+   image, so it stays pixel-aligned with the final document and baseline
+   exclusion keeps working instead of being skipped. Verified in isolation:
+   `page_tilt` alone at maximum strength now detects 552 ink pixels (vs.
+   545 with no tilt at all) -- effectively fixed.
+
+   **A separate, smaller contamination source was found (not fixed) while
+   verifying #4 above:** forcing `scanner_noise`/`salt_pepper`/`dust` on
+   simultaneously with everything else -- as the lever's "Explore from
+   clean (all effects)" mode deliberately does -- inflates detected ink
+   pixels through a *different* mechanism: the geometry pipeline scores a
+   signature using the convex hull/bounding box of *every* surviving "ink"
+   pixel, so even a few scattered noise specks near opposite corners of the
+   search box balloon that box to span nearly the whole region, regardless
+   of how little total dark area they cover (measured: ink pixel *count*
+   only roughly doubled, but IoU-with-box jumped from 0.11 to 0.82). A
+   median-blur denoise pre-pass was prototyped as a fix and rejected: a
+   kernel strong enough to meaningfully suppress noise at extreme,
+   all-effects-maxed strength (5x5) also cut a genuinely clean sample's
+   real ink-pixel count by ~60% (403 -> 157) -- real pen strokes are only a
+   few pixels wide, the same order of magnitude as the noise being
+   filtered, so the fix would trade real detection accuracy for a mostly
+   synthetic problem. A shape/cluster-aware alternative (discard ink
+   components far from the "main" cluster) was also rejected: it directly
+   conflicts with this same section's existing, deliberate design (the
+   hull is meant to *bridge* a genuine flourish far from the main strokes,
+   not discard it) and would need real testing against genuine faint/thin
+   signatures to avoid new false negatives -- a bigger investment than
+   warranted, since at realistic (non-maxed) strengths the effect is mild
+   (measured: only ~8% ink-pixel inflation at strength 0.3, vs. 25x for the
+   page_tilt bug above). Left as a documented limitation of the "Explore
+   from clean (all effects)" lever mode specifically -- which stacks all 14
+   effects simultaneously, something real generation never does (each
+   effect fires independently/probabilistically) -- rather than changing
+   detection logic; the lever now shows an explicit warning above 25% in
+   that mode instead of a silently-misleading score.
+
+## Placement floor: 28px, not the deck's 16px -- resolved by measurement, not forced
+
+A full line-by-line audit against `Metrics_Thresholds_Formulas.pptx`'s
+"Threshold reference sheet" slide found every constant in this pipeline
+matches exactly except one: `min_signature_height_px`
+(`src/config/schema.py::PlacementConfig`, formerly a
+`placement_engine.py` module constant) is 24px-then-28px in code vs. the
+deck's 16px. Rather than silently override it to match the deck, or leave
+it unexplained, this was resolved empirically: a real signature was placed
+into a genuine short 18px "sign here" line (the deck's own "real lines are
+12-20px tall" range) at each floor value and the result measured directly.
+
+| Floor | Placed height | Fully-opaque ink (alpha > 200/255) |
+|---|---|---|
+| 16px (deck) | 16px | 12.3% |
+| 24px (first pass) | 22px | 15.1% |
+| 28px (current, see "Placement calibration" above) | -- | 16.8% |
+
+Each step up measurably preserves more solid, legible ink -- `cv2.INTER_AREA`
+dilutes a multi-pixel source stroke's alpha the smaller the downscale
+target gets, and 16px sits deepest in that dilution zone (the same artifact
+already described in this file's placement-scaling comments). 32px was
+also tested (see "Placement calibration" above) and rejected -- overflow
+past 28px escalates much faster than the legibility gain. The constant's
+own definition cites this measurement directly, the same way
+`DifficultyWeights`' smallness/faintness constants document their own
+deliberate deviation from the deck's generic values.
+
+This was one finding from a full line-by-line audit (every formula/
+threshold/case-type in the deck checked against this codebase) -- 52 of 53
+checks matched exactly; this was the one documented deviation, resolved by
+measurement rather than left silently unexplained.
+
+## The ink polygon on the preview tints the real ink, not the hull
+
+Several rendering styles were tried this session, in order, each fixing
+the previous one's complaint:
+
+1. **Hull, outline only** (the original design). A convex hull "bridges"
+   gaps between separate ink blobs (letters, a flourish far from the main
+   strokes) with straight lines -- the bridging edges visibly don't hug
+   the ink wherever they cross a gap. Reported: "the polygon doesn't even
+   cover the signature."
+2. **Hull, translucent fill.** Fixed #1 (the ink is always inside the
+   tinted region), but a filled hull shades in every gap it bridges too.
+   Reported, correctly: "shouldn't [it] only cover surround the signature
+   not whitespaces."
+3. **Hull outline + `cv2.approxPolyDP` simplification** (a vertex-count
+   reduction on the hull polygon). Still visibly failed to "hug" a
+   wide/gappy signature on direct re-inspection, since it's still
+   fundamentally the same convex hull -- a known tradeoff of hull-based
+   rendering that just isn't obvious on a small, compact signature.
+4. **`display_contours`, translucent fill** (current, final). A
+   purely-visual field on `GeometryResult`: one real boundary contour per
+   disjoint ink blob, via `cv2.findContours` on the exact mask used for
+   scoring (mildly dilated first, on a copy, just to merge one letter's
+   own stroke fragments into a single blob -- nowhere near enough to
+   bridge a real gap between separate letters). Filling each blob's own
+   contour tints only actual ink, never the whitespace between strokes,
+   and -- unlike an *outline* of these same contours (tried and rejected
+   earlier: for a dense cursive/Devanagari signature it visually resembled
+   a second overlaid signature) -- a fill has no separate line art to be
+   confused with handwriting.
+
+`signature_polygon_px`/`convex_hull_px` in `ground_truth.json` remain the
+convex hull (with the `approxPolyDP` simplification from step 3 kept, as a
+minor genuine improvement to the scoring polygon's vertex count) -- every
+coverage metric (`box_coverage_pct`/IoU/`containment_pct`/`margin_utilization`)
+still comes from the hull, unchanged. `display_contours` is additive and
+explicitly documented as "never used in scoring." Both
+`before_after_preview.py` and `visualizer.py` (`--save-visualization`)
+fill `display_contours` when present, falling back to filling the hull for
+any geometry dict that predates this field. This was a deliberate choice,
+made after comparing several rendering styles directly -- prioritizing an
+accurate, non-misleading preview over hull-only visual simplicity.
+
+## Metrics preview shows every signed box, not just the scored one
+
+A multi-box template's companion/additional-signature boxes are genuinely
+rendered with real ink but aren't part of a sample's *scored* target
+(geometry/difficulty stay keyed to the one target box the rest of the
+pipeline scores) -- previously the before/after metrics preview only ever
+overlaid that one box, leaving a second signature elsewhere on the page
+unexplained. `compute_extra_signature_overlays()` (`src/generator.py`)
+re-runs `GeometryAnalyzer` (view-only, never for scoring) on every other
+signed box for the preview, and `save_before_after_preview()`'s
+`extra_boxes` param draws them in a distinct purple/pink palette, labeled
+by role (e.g. "Account Holder (other box)") instead of full re-scoring.
+
+## Reference-signer index
+
+`scripts/generate_showcase_dataset.py` also writes
+`data/showcase_dataset/reference_signers_index.json` -- every distinct
+name/role that appears anywhere in the dataset (as a primary signer,
+companion, or additional/other-box signer), with which signer identity
+backs it and where its ink actually comes from:
+
+```json
+{
+  "signer_group": "signet_0009",
+  "display_name": "John Thompson",
+  "script": "latin",
+  "roles": ["Bank Manager"],
+  "appears_in": [{"case_id": "case_001_1a_scanned", "role": "Bank Manager", "as": "primary", "template": "bank_doc_08"}],
+  "reference_images": ["data/raw/signet/train/009/009_24.PNG"]
+}
+```
+
+`signer_group` is the pipeline's internal, deterministic identity key
+(`src/verification/registry.py::SignerIdentityRegistry`) -- `display_name`
+is the human-readable name derived from it, stable across every case that
+identity appears in. `appears_in` distinguishes *how* that identity was
+used in each case (`"primary"` = the case's own target signer, `"companion"`
+= the officially-tested second signer for `1c`/`4a`/`4b`/`5a`/`5b`,
+`"additional"` = an unrelated-but-still-genuine extra box fill -- see
+"Every signature box on a multi-box template gets signed" above).
+`reference_images` collects every distinct source image path used for that
+identity across the whole dataset (not just one case), each already copied
+into its case folder too (`*_reference_signature.png` /
+`*_companion_signature.png` / `*_<box_id>_signature.png`) so nothing here
+depends on `data/raw/` actually being present to inspect a specific case.
+
+## Multi-signature-box logic, audited (and a real gap fixed)
+
+Every case type that needs two signature boxes (`1c`, `4a`, `4b`, `5a`,
+`5b` -- see `CASE_TABLE`'s `fill_companion` flag) was verified end-to-end
+across both scanned and procedural 2-box templates: template selection
+correctly restricts to templates with >=2 boxes, the companion box is
+always filled with its own correct authorized signer, and the target box
+gets exactly what its case type specifies (`1c`: also correct; `4a`: the
+*companion's* signer, in the wrong box, same form; `4b`: a signer
+authorized on a *different* template entirely; `5a`: left blank; `5b`: an
+unrelated wrong signer) -- confirmed both from the ground-truth JSON
+(`expected_signer_group` vs `actual_signer_group` vs the companion's
+group) and from rendered images.
+
+**Gap found and fixed:** case types that *don't* officially test a second
+signer (`1a`, `1b`, `1d`, `2a`, `2b`, `3a`, `3b` -- `fill_companion=False`)
+and plain generic (no `quality.case_type` at all) samples were leaving any
+*extra* box on a multi-box template completely blank, with no verdict or
+reject_code explaining why -- it just looked like a broken render. Fixed
+in both `_run_generic_sample` and `_run_case_sample`
+(`src/generator.py`): any signature box beyond the one the sample is
+actually scored/tested against now gets filled with its own correct
+authorized signer too, recorded under the new `additional_signatures`
+metadata field (list of `{box_id, role, signature_id, signer_group,
+source_type, script, ref_path}`) and copied into the case folder as
+`..._<box_id>_signature.png`. This only ever *adds* a properly-signed box
+-- it never overrides a case type's own deliberate blank/wrong-signer
+target (verified: a `2a` case's target box is still correctly blank with
+`NO_SIGNATURE`, while its unrelated second box is now properly signed
+instead of mysteriously empty).
+
+One real annotation bug found and fixed in the process: `bank_doc_09`'s
+bundled signature-box annotation (`annotations/bank_doc_09.json`,
+inherited as-is from an earlier revision) placed both boxes 27px too
+high -- inside the paragraph text above the "First/Second Authorised
+Signatory" line instead of on it. Found by rendering a sample and looking
+at where the ink actually landed (not visible from the annotation JSON
+alone), confirmed against the template's real line position via the same
+CV line-detector `scanned_cosmetic_fields.py` uses, and corrected.
+
+## A bug worth knowing about (fixed): reference signature images
+
+An earlier version of the per-case output copied the reference signature
+file with `shutil.copy2` under a `*_reference_signature.png` name. For
+CEDAR/SigNet sources (already `.png`) that's fine; for **BHSig260 sources
+(`.tif` files)** it silently produced a file containing real TIFF bytes
+under a `.png` name -- any standards-compliant image viewer correctly
+refuses to open it. Fixed by decoding with Pillow and re-saving as a real
+PNG (`src/generator.py::_export_reference_signature`) -- every reference/
+companion signature image is now guaranteed to actually be what its
+extension claims. Regression test: `tests/test_scanned_cosmetic_fields.py::test_export_reference_signature_produces_a_real_png_from_a_tiff_source`.
+
+## Usage
+
+```bash
+pip install -r requirements.txt
+
+# The flagship demo -- all 12 case types x both template families, 24 cases
+python scripts/generate_showcase_dataset.py
+# (already generated once into data/showcase_dataset/ -- rerun to regenerate)
+
+# Default: both template pools, deck-literal difficulty constants
+python main.py --count 20 --seed 1
+
+# Procedural only, recalibrated difficulty constants
+python main.py --config configs/procedural_templates.yaml --count 20 --seed 1
+
+# Scanned only
+python main.py --set paths.template_provider=scanned --count 20 --seed 1
+
+# A specific case type (see src/verification/case_types.py for all 12)
+python main.py --config configs/procedural_templates.yaml --set quality.case_type=3b --count 10
+
+# Request a specific difficulty score, with a before/after preview
+python main.py --count 5 --target-difficulty 0.55 --save-before-after
+```
+
+## Interactive UI
+
+```bash
+streamlit run streamlit_app.py
+```
+
+A local browser UI (`streamlit_app.py`) for one-off, customizable document
+creation -- pick template provider/id (picking a specific template shows a
+live preview of its blank form, with its document type and signature-box
+roles, right below the dropdown, before you even generate anything), case
+type (with its own description/verdict shown inline), a natural or
+targeted difficulty (as a plain percentage, not a raw `0.0-1.0` score), a
+**difficulty calibration** toggle (see below), signer name/role overrides,
+cosmetic fields on/off, and a seed, then generate and immediately see the
+rendered document, verdict, and a plain difficulty percentage (the
+easy/medium/hard tier is kept in the ground-truth data for case-type
+validation, but isn't the headline UI number anymore -- a caption under
+the percentage shows it for anyone who wants it), and (organized into tabs
+to keep the page scannable):
+- **Difficulty & degradation** -- what actually built the difficulty score
+  (a labeled progress bar per weighted component --
+  misplacement/whitespace/faintness/smallness/low texture, each with a
+  one-line plain-English explanation) and which degradation effects
+  actually, randomly fired for this specific sample (not just which were
+  possible). Difficulty calibration is now automatic per sample (see
+  "Difficulty calibration profiles" above) -- procedural samples get
+  `smallness_reference_area_ratio=0.003` / `faintness_dark_ref/light_ref=
+  165/220` / `low_texture_reference_stddev=46` and scanned samples keep the
+  deck-literal `0.04` / `90` / `210` / `60`, without needing to opt in. The
+  sidebar's **"Force deck-literal reference for ALL templates"** checkbox
+  (off by default) is only there to deliberately turn this OFF -- forcing
+  every sample, including procedural ones, back onto the deck-literal
+  constants that peg smallness/faintness near their ceiling for almost any
+  real signature (real signature area is only ~0.2-1.5% of the page vs. the
+  deck's 4% "normal"), e.g. to compare
+  against pre-recalibration scores.
+- **Interactive lever** -- drag a slider to watch the same clean render
+  pass through progressively stronger document degradation live, without
+  re-running the whole pipeline. Three modes: *match this document*
+  (default) scales only the effects that actually fired, together, from
+  0% (clean) to 100% (this document's real per-effect strengths -- so it
+  closely matches the Before/After tab, modulo the lever using its own
+  seed key for random-variant choices like stain shape/shadow corner);
+  *adjust individually* gives one slider per document-level effect,
+  defaulted to what actually fired (0% if it didn't), so you can push any
+  single effect harder/weaker/on independently of the rest; *explore from
+  clean* ignores what actually fired entirely and forces all 14 effects on
+  together at one shared strength, starting from clean -- a generic
+  worst-case stress-test (this is what the original version of the lever
+  always did, kept as its own mode). Both the clean and degraded preview
+  now show a live `difficulty_score`, freshly re-detected from the
+  pictured image with the same `GeometryAnalyzer`/`DifficultyAnalyzer` the
+  real pipeline uses -- it updates as you drag, but is computed
+  independently of (and can legitimately differ from) the "Difficulty"
+  badge at the top of the page, which reflects the actual generated
+  document. The lever only covers the 14 whole-page effects
+  (`apply_to_document()`) -- the 6 signature-only effects (rotation,
+  stroke thickness, ink bleed/fading, blur) run earlier, on the signature
+  snippet alone before it's pasted onto the page, so they're already baked
+  into "Clean" as plain pixels and can't be toggled here; a warning banner
+  surfaces exactly which of them fired (if any) for the current sample, so
+  the gap is visible rather than silent.
+- **Before / After (real)** -- the saved before/after preview PNG, with a
+  note that BEFORE's colored boxes are a measurement diagnostic
+  (target/detected/cosmetic-field boxes) and AFTER deliberately has no
+  overlay, since it's meant to show what a real reviewer/scanner would see.
+- **Ground truth & export** -- the full ground-truth JSON, the equivalent
+  `python main.py --set ...` CLI command (every control is a thin wrapper
+  over a config override the CLI already accepts, so anything built in the
+  UI is exactly reproducible from the command line), and "Save this case",
+  which writes the document/ground-truth/reference-signature into
+  `data/ui_generated/<name>/`, in the same per-case-folder shape as
+  `output/`/`data/showcase_dataset/`.
+
+## Tests
+
+```bash
+python -m pytest -q   # 119 passed, ~2-3 min
+```
+
+Covers formula correctness, placement, augmentation, validation, all 12
+case types, end-to-end reproducibility, `ProceduralTemplateProvider`,
+`CompositeTemplateProvider`, the additive signature sources, and the two
+difficulty-calibration profiles.