From 13d07eb0b39c850f107a10f6d7e240f9d0b415bf Mon Sep 17 00:00:00 2001
From: Jan Svabenik <jan@svabi.ch>
Date: Sun, 22 Mar 2026 08:03:28 +0100
Subject: [PATCH] Update docs and config for refinement detail path

---
 PLAN.md     |  5 +++++
 README.md   |  9 +++++----
 config.yaml | 45 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 55 insertions(+), 4 deletions(-)

diff --git a/PLAN.md b/PLAN.md
index f26839f..8e2b1ff 100644
--- a/PLAN.md
+++ b/PLAN.md
@@ -96,6 +96,9 @@ Neue Konfig-Teile einführen:
 - `resources.*`
 - optionale `profiles.*`
 
+Zusatz:
+- `refinement.detail_fft_size` für einen eigenständigen Detailpfad (Refinement-FFT) neben der Surveillance-FFT
+
 Wichtig:
 - Abwärtskompatibilität zur bisherigen Config möglichst erhalten
 - bisherige Felder weiterhin nutzbar
@@ -110,6 +113,7 @@ Wichtig:
 - zunächst mit CPU-/bestehendem GPU-Extraction-Pfad implementieren
 - Detector bleibt vorerst Kern der Candidate-Erzeugung
 - Refiner sitzt danach explizit als eigener Schritt in der Pipeline
+- Refinement-Workitems mit expliziten Ausführungsparametern (FFT/Span/Stage)
 
 ### E. Pipeline-Orchestrierung modularisieren
 - `runDSP()` entflechten
@@ -122,6 +126,7 @@ Wichtig:
   - track
   - present
   - record
+- Gemeinsame Arbitration-/Budget-Sicht für refinement/record/decode vorbereiten
 
 ### F. Dokumentierte Betriebsprofile
 - initiale Profile definieren, z. B.:
diff --git a/README.md b/README.md
index 59305f1..57b2567 100644
--- a/README.md
+++ b/README.md
@@ -70,15 +70,16 @@ Edit `config.yaml` (autosave goes to `config.autosave.yaml`).
 - `surveillance.display_fps` — preferred presentation cadence for clients/UI
 - `refinement.enabled` — enables explicit candidate refinement stage
 - `refinement.max_concurrent` — refinement budget hint
+- `refinement.detail_fft_size` — FFT size for refinement/detail path (defaults to surveillance analysis FFT)
 - `refinement.min_candidate_snr_db` — floor for future scheduling decisions
 - `refinement.min_span_hz` / `refinement.max_span_hz` — clamp refinement window span (0 = no clamp)
 - `refinement.auto_span` — use mod-type heuristics when candidate bandwidth is missing/odd
 - `resources.prefer_gpu` — GPU preference hint
 
 **Operating profiles (wideband)**
-- `wideband-balanced`: multi-resolution, 4096 FFT, refinement span 4000-200000 Hz
-- `wideband-aggressive`: multi-resolution, 8192 FFT, refinement span 6000-250000 Hz
-- `archive`: record-forward bias, higher record/decode budgets
+- `wideband-balanced`: multi-resolution, 4096 surveillance/detail FFT, refinement span 4000-200000 Hz
+- `wideband-aggressive`: multi-resolution, 8192 surveillance/detail FFT, refinement span 6000-250000 Hz
+- `archive`: record-forward bias, higher record/decode budgets, 4096 detail FFT
 - `digital-hunting`: digital-first priorities and decode bias
 - `resources.max_refinement_jobs` — processing budget hint
 - `resources.max_recording_streams` — recording/streaming budget hint
@@ -158,7 +159,7 @@ go build -tags sdrplay ./cmd/sdrd
 - `GET /api/gpu`
 - `GET /api/pipeline/policy`
 - `GET /api/pipeline/recommendations`
-- `GET /api/refinement` → latest refinement plan/windows snapshot (includes `window_stats`, `queue_stats`, `decision_summary`, `decision_items`, levels, request/context/budgets/work_items)
+- `GET /api/refinement` → latest refinement plan/windows snapshot (includes `window_stats`, `queue_stats`, `decision_summary`, `decision_items`, `arbitration`, levels, request/context/budgets/work_items)
 
 ### Signals / Events
 - `GET /api/signals` → current live signals
diff --git a/config.yaml b/config.yaml
index 93a8750..f4646d2 100644
--- a/config.yaml
+++ b/config.yaml
@@ -30,6 +30,7 @@ surveillance:
 refinement:
   enabled: true
   max_concurrent: 8
+  detail_fft_size: 2048
   min_candidate_snr_db: 0
   min_span_hz: 0
   max_span_hz: 0
@@ -37,13 +38,34 @@ refinement:
 profiles:
   - name: legacy
     description: Current single-band pipeline behavior
+    surveillance:
+      analysis_fft_size: 2048
+      strategy: single-resolution
+    resources:
+      max_refinement_jobs: 8
+      max_recording_streams: 16
+      max_decode_jobs: 16
+      decision_hold_ms: 2000
+    refinement:
+      max_concurrent: 8
+      detail_fft_size: 2048
     pipeline:
       mode: legacy
       goals:
         intent: general-monitoring
   - name: wideband-balanced
     description: Prepared baseline for scalable wideband surveillance
+    surveillance:
+      analysis_fft_size: 4096
+      strategy: multi-resolution
+    resources:
+      max_refinement_jobs: 16
+      max_recording_streams: 16
+      max_decode_jobs: 12
+      decision_hold_ms: 2000
     refinement:
+      max_concurrent: 16
+      detail_fft_size: 4096
       min_span_hz: 4000
       max_span_hz: 200000
     pipeline:
@@ -52,7 +74,17 @@ profiles:
         intent: wideband-surveillance
   - name: wideband-aggressive
     description: Higher surveillance/refinement budgets for future broad-span monitoring
+    surveillance:
+      analysis_fft_size: 8192
+      strategy: multi-resolution
+    resources:
+      max_refinement_jobs: 32
+      max_recording_streams: 24
+      max_decode_jobs: 16
+      decision_hold_ms: 2000
     refinement:
+      max_concurrent: 32
+      detail_fft_size: 8192
       min_span_hz: 6000
       max_span_hz: 250000
     pipeline:
@@ -61,6 +93,19 @@ profiles:
         intent: high-density-wideband-surveillance
   - name: archive
     description: Record-first monitoring profile
+    surveillance:
+      analysis_fft_size: 4096
+      strategy: single-resolution
+    resources:
+      max_refinement_jobs: 12
+      max_recording_streams: 24
+      max_decode_jobs: 12
+      decision_hold_ms: 2500
+    refinement:
+      max_concurrent: 12
+      detail_fft_size: 4096
+      min_span_hz: 4000
+      max_span_hz: 200000
     pipeline:
       mode: archive
       goals: