docs: LNK-031 hardware-verify + ADR-0004 (touch vs web config responsibilities)

docs/adr/0004-touch-realtime-web-config.md

@@ -0,0 +1,45 @@
+# 4. Touch screen carries real-time controls; static config lives in the web UI
+
+Date: 2026-07-04
+Status: accepted
+
+## Context
+
+X32Link has two config surfaces: the **web config UI** (rack-panel page served
+over WiFi) and the on-device **1.47" touch LCD settings screen** (LNK-014/015).
+During the LNK-032 config-edit review a gap surfaced: `midi_clock_out_enable`
+(LNK-027) can be set from the web UI but has no control on the touch settings
+screen — and that screen is already full (source / model / FX slot / quantum /
+mixer IP / Write & Reboot).
+
+The question: make room on the touch screen for every config field so the two
+editors stay at parity, or accept that the touch screen intentionally shows a
+subset?
+
+## Decision
+
+The **web UI is the complete config surface**. The **touch screen carries only
+controls a user would plausibly change in real time, at the rack** — plus live
+status (the phase wheel, BPM) — not static setup that requires a reboot to take
+effect.
+
+- Reboot-gated setup — WiFi credentials, mixer IP/model, FX slot, and
+  `midi_clock_out_enable` — is a "configure once, Write & Reboot" concern and
+  belongs on the web page.
+- The touch screen is for on-the-fly changes (e.g. bar quantum) and live readout.
+
+So `midi_clock_out_enable` having no touch control is **intentional, not a bug**:
+it's a reboot-gated config flag, not a real-time control.
+
+## Consequences
+
+- The touch settings screen stays uncluttered and focused; not every web field
+  needs a touch twin — the two editors are deliberately **not** at full parity.
+- The LNK-032 shared config-edit helpers (`config_set_model`, and future
+  `config_set_*`) still let both editors share clamp/dependency rules for the
+  fields they *do* both expose.
+- Future architecture reviews should **not** re-flag "the touch UI can't set
+  field X" as a defect for reboot-gated config fields — that is this decision,
+  not drift. (This closes the LNK-032 "touch can't set midi_clock_out" item as
+  won't-do rather than deferred.)
+- If a field becomes real-time-relevant later, it can earn a touch control then.

esp32/tasks/LNK-031.md

@@ -64,12 +64,15 @@ in `link_measurement.c` stay as-is and are called by the session or the glue.
       session's actions (`run_action`); behaviour faithfully ported (LNK-026
       fixes preserved as session actions).
 - [x] Full host suite green (20 suites); firmware compiles 86%; `AGENTS.md` updated.
-- [x] **Steady-play re-verified on hardware** (flashed; Link peer @ 127 BPM):
-      `valid` holds true, phase advances smoothly at the correct rate and wraps
-      cleanly through the quantum with no garbage spikes — the session drives the
-      sockets correctly end-to-end, measurement path intact. The stop/start
-      re-origin path is host-tested (epoch-reset actions) but wasn't re-driven via
-      Ableton transport this pass; low risk given the faithful port + tests.
+- [x] **Re-verified on hardware** (flashed; Link peer @ 127 BPM). Steady play:
+      `valid` holds, phase advances at the correct rate, no garbage. **Re-origin:
+      user drove an Ableton transport stop/start while watching the LCD phase
+      wheel — it holds momentarily (the re-measure window) then re-locks cleanly,
+      no erratic garbage (the original LNK-026 symptom).** Wheel sweeps smoothly =
+      no loop-blocking regression from the refactor. Note: no distinct "syncing"
+      text (the wheel renders the brief `valid:false` as a clean pause). Session
+      orchestrator confirmed end-to-end. (HTTP `/status` is too low-throughput to
+      catch the ~1-2s syncing window by polling — the LCD wheel is the instrument.)
 
 ## Notes
 

esp32/tasks/LNK-032.md

@@ -65,8 +65,10 @@ and part of the divergence is **intentional and documented**:
       clamp-on-downshift, and ignore-invalid-model.
 - [x] Both editors use it: `web_config.cpp handle_save()` and `touch_ui.c
       ui_apply_settings_tap()` — web now inherits the same slot re-clamp.
-- [~] `midi_clock_out` touch divergence: **deferred** — it's layout-gated, not a
-      duplication fix (see above). Tracked as the LNK-027 touch-screen follow-on.
+- [x] `midi_clock_out` touch divergence: **won't-do (intentional)** — resolved by
+      **ADR-0004**: the web UI is the complete config surface; the touch screen
+      carries only real-time controls, and `midi_clock_out_enable` is a
+      reboot-gated config flag. Not a bug, so no touch control is added.
 - [x] Quantum reject-vs-clamp divergence: intentionally preserved (documented).
 - [x] Full host suite green (19 suites); firmware compiles 86%.