some fixes

docs/run_config.md

@@ -232,6 +232,42 @@ Use mock switches on a laptop without GPIO:
 "driver_mode": "mock"
 ```
 
+## `control_button`
+
+Optional physical GPIO push-button that triggers a runtime action on press.
+The watcher runs in both GUI and headless modes (it is attached to the main
+window, which both launch paths build). On press it reuses the existing
+"Capture Tmp Reference" flow: stop the pipeline, capture a fresh tmp S21
+reference with the current sweep settings, then restart the pipeline if it had
+been running.
+
+```json
+"control_button": {
+  "enabled": true,
+  "gpio_chip": "/dev/gpiochip0",
+  "pin": 26,
+  "active_low": true,
+  "bias": "",
+  "debounce_ms": 50,
+  "action": "capture_tmp_reference"
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `enabled` | Master switch. When `false` (default) no GPIO line is opened, so non-Pi hosts are unaffected. |
+| `gpio_chip` | Linux GPIO chip path, usually `/dev/gpiochip0`. |
+| `pin` | BCM line offset of the button. `26` is physical pin 37, with GND on physical pin 39. |
+| `active_low` | `true` for a button wired to GND with the internal pull-up: the line idles high and a press is detected on the falling edge. `false` mirrors this for a button wired to 3V3 with a pull-down (rising edge). |
+| `bias` | Internal bias override: `pull_up`, `pull_down`, or `disabled`. Empty (default) derives the bias from `active_low`. |
+| `debounce_ms` | Hardware debounce period applied by the kernel, in milliseconds. |
+| `action` | Action to run on press. Currently only `capture_tmp_reference`. |
+
+Occupied BCM lines (native switches) are `17`, `22`, `23`, `27`; pick a free
+line such as `16`, `20`, `21`, or `26` for the button. A failure to open the
+line (missing chip, line already in use) is logged as a warning and never
+aborts startup.
+
 ## `run`
 
 Runtime behavior and combo selection.