docs(config): mark target_fps legacy; describe what Vegas scroll_delay does

- General tab "Scroll Frame Rate" (target_fps) is labelled legacy: after
  the sports_scroll fix nothing in core scrolling reads it. The field and
  its API validation stay so saved configs and plugins that read
  global_config['target_fps'] keep working. CONFIG_REFERENCE says the same.
- Vegas frame_based_scrolling/scroll_delay were described as frame-count
  stepping at ~50 FPS. Neither steps nor sets a frame rate: frame-based
  mode converts the speed to px per scroll_delay, clamps it to 0.1-5, and
  still advances by elapsed time, so the applied speed is
  clamp(scroll_speed * scroll_delay, 0.1, 5) / scroll_delay px/s. The
  config comments, render_pipeline comment and CONFIG_REFERENCE rows now
  say so. No behaviour change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/CONFIG_REFERENCE.md

@@ -17,7 +17,7 @@ tooling against it.
 |---|---|---|---|
 | `web_display_autostart` | bool, `true` | Whether the web interface service starts with the system | `scripts/utils/start_web_conditionally.py` |
 | `timezone` | string, `"America/New_York"` | IANA timezone for schedules and displays | `ConfigManager.get_timezone()` |
-| `target_fps` | int, `100` | Frame-rate ceiling for plugin rendering | `src/plugin_system/base_plugin.py`, `src/common/sports_scroll.py` |
+| `target_fps` | int, `100` | Legacy "Scroll Frame Rate". Core scrolling no longer reads it: scroll frames are presented at `display.hardware.limit_refresh_rate_hz` divided by each scroll's frame hold, and speed comes from each plugin's scroll settings. Still exposed to plugins via `BasePlugin.global_config` | `src/plugin_system/base_plugin.py` |
 | `location` | object | `city` / `state` / `country`. Supplies the **default** for a plugin's own `location_city` / `location_state` / `location_country` setting, so weather, radar and friends follow this device without being configured twice. A value saved on the plugin itself still overrides it. | `SchemaManager.apply_device_location()`, then plugins via merged config |
 
 ## `schedule` — display on/off hours
@@ -134,8 +134,8 @@ Read by `src/vegas_mode/config.py` (`VegasScrollConfig.from_config`). See
 | `dynamic_duration_enabled` | bool, `true` |
 | `min_cycle_duration` | int, `60` |
 | `max_cycle_duration` | int, `240` |
-| `frame_based_scrolling` | bool, `true` — frame-count-based scroll stepping |
-| `scroll_delay` | float, `0.02` — seconds between scroll updates (~50 FPS) |
+| `frame_based_scrolling` | bool, `true` — does not step or set a frame rate; motion is by elapsed time either way. When `true`, `scroll_speed` passes through a clamp of 0.1–5 px per `scroll_delay` (see next row) |
+| `scroll_delay` | float, `0.02` — not a frame period. Only used with `frame_based_scrolling`: the applied speed is `clamp(scroll_speed × scroll_delay, 0.1, 5) / scroll_delay` px/s, so at `0.02` speeds under 5 px/s run at 5, and at `0.001` nothing runs slower than 100 px/s |
 | `live_in_ticker` | bool, `false` — keep scrolling during live games instead of handing the display to a full-screen scoreboard |
 | `live_weight` | int, `3` (1–10) — slots per cycle for a plugin with live content |
 | `favorite_live_weight` | int, `5` (1–10) — slots per cycle when a plugin reports a favorite team is live |

src/vegas_mode/config.py

@@ -155,9 +155,14 @@ class VegasModeConfig:
     target_fps: int = 125  # Target frame rate
     buffer_ahead: int = 2  # Number of plugins to buffer ahead
 
-    # Scroll behavior
+    # Scroll behavior. Neither key steps the scroll or sets a frame rate:
+    # motion is always by elapsed time at scroll_speed px/s. With
+    # frame_based_scrolling the speed is first converted to px per
+    # scroll_delay and clamped to 0.1-5 (ScrollHelper.set_scroll_speed), so
+    # the speed actually applied is clamp(scroll_speed * scroll_delay, 0.1, 5)
+    # / scroll_delay -- at the 0.02 default, speeds under 5 px/s run at 5.
     frame_based_scrolling: bool = True
-    scroll_delay: float = 0.02  # 50 FPS effective scroll updates
+    scroll_delay: float = 0.02  # only feeds the clamp above; not a frame period
 
     # Dynamic duration
     dynamic_duration_enabled: bool = True

src/vegas_mode/render_pipeline.py

@@ -127,12 +127,14 @@ class RenderPipeline:
         self.scroll_helper.set_sub_pixel_scrolling(self.config.smooth_scroll)
 
         # Config scroll_speed is always pixels per second, but ScrollHelper
-        # interprets it differently based on frame_based_scrolling mode:
-        # - Frame-based: pixels per frame step
-        # - Time-based: pixels per second
+        # takes it in different units depending on frame_based_scrolling:
+        # - Frame-based: pixels per scroll_delay seconds (clamped to 0.1-5)
+        # - Time-based: pixels per second (clamped to 1-500)
+        # Both modes then advance by elapsed time; frame-based mode does not
+        # step. So frame-based with scroll_delay only adds the clamp: the
+        # applied speed is clamp(scroll_speed * scroll_delay, 0.1, 5) /
+        # scroll_delay px/s.
         if self.config.frame_based_scrolling:
-            # Convert pixels/second to pixels/frame
-            # pixels_per_frame = pixels_per_second * seconds_per_frame
             pixels_per_frame = self.config.scroll_speed * self.config.scroll_delay
             self.scroll_helper.set_scroll_speed(pixels_per_frame)
         else:

web_interface/templates/v3/partials/general.html

@@ -88,9 +88,9 @@
             <div id="timezone_container" class="mt-1"></div>
         </div>
 
-        <!-- Scroll frame rate (device-wide) -->
+        <!-- Legacy scroll frame rate (device-wide). Core scrolling no longer reads it. -->
         <div class="form-group" id="setting-general-target-fps" data-setting-key="target_fps">
-            <label for="target_fps" class="block text-sm font-medium text-gray-700">Scroll Frame Rate{{ ui.help_tip('Frames per second for scrolling content, applied across plugins that scroll.\nHigher is smoother but uses more CPU; lower frees CPU but looks steppier.\nRange 30-200. Default: 100.', 'Scroll Frame Rate') }}</label>
+            <label for="target_fps" class="block text-sm font-medium text-gray-700">Scroll Frame Rate (legacy){{ ui.help_tip('Kept for older plugins that read it. It no longer changes scrolling speed or smoothness.\nScrolling runs at the panel refresh rate (Display settings), and each plugin sets its own scroll speed.\nRange 30-200. Default: 100.', 'Scroll Frame Rate (legacy)') }}</label>
             <input type="number"
                    id="target_fps"
                    name="target_fps"