docs(olympics): document all 25 settings, and record two live defects

README.md

@@ -99,7 +99,7 @@ curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \
 | [NFL Draft](./plugins/nfl-draft/) | Projected & live NFL draft picks from ESPN | |
 | [Odds Ticker](./plugins/odds-ticker/) | Betting odds & lines across NFL, NBA, MLB, NHL, NCAA | |
 | [Sports Leaderboard](./plugins/ledmatrix-leaderboard/) | League standings, rankings, conference records | |
-| [Olympics Countdown](./plugins/olympics/) | Countdown to next Olympics with live medal counts | |
+| [Olympics Countdown](./plugins/olympics/) | Countdown to next Olympics with live medal counts | <a href="./plugins/olympics/"><img src="./docs/assets/olympics/hero.png" width="240" alt="olympics on an LED panel"></a> |
 
 ### Financial (2)
 

docs/assets/olympics/shots.json

@@ -0,0 +1,95 @@
+{
+  "plugin": "olympics",
+  "_comment": "The countdown needs no fetched data, so these render offline. The medal, schedule and results sections need live Games data (an OlympicsData object built by the fetcher), which no config or cache seed can stand in for, so they are described rather than pictured.",
+  "defaults": {
+    "width": 128,
+    "height": 32,
+    "scale": 6,
+    "freeze_time": "2026-09-03T12:00:00+00:00",
+    "skip_update": true,
+    "config": {
+      "enabled": true
+    }
+  },
+  "shots": [
+    {
+      "name": "hero",
+      "freeze_time": "2026-01-05T12:00:00+00:00"
+    },
+    {
+      "name": "before-games",
+      "freeze_time": "2026-01-05T12:00:00+00:00",
+      "standalone": false
+    },
+    {
+      "name": "after-games",
+      "freeze_time": "2026-09-03T12:00:00+00:00",
+      "standalone": false
+    },
+    {
+      "name": "size-64x32",
+      "width": 64,
+      "freeze_time": "2026-01-05T12:00:00+00:00",
+      "standalone": false
+    },
+    {
+      "name": "size-128x32",
+      "width": 128,
+      "freeze_time": "2026-01-05T12:00:00+00:00",
+      "standalone": false
+    },
+    {
+      "name": "size-128x64",
+      "width": 128,
+      "height": 64,
+      "freeze_time": "2026-01-05T12:00:00+00:00",
+      "standalone": false
+    },
+    {
+      "name": "size-256x32",
+      "width": 256,
+      "freeze_time": "2026-01-05T12:00:00+00:00",
+      "standalone": false
+    }
+  ],
+  "composites": [
+    {
+      "name": "countdown-state",
+      "columns": 1,
+      "cells": [
+        {
+          "shot": "before-games",
+          "label": "Before the Games",
+          "sublabel": "32 days out from Milano Cortina"
+        },
+        {
+          "shot": "after-games",
+          "label": "After the Games",
+          "sublabel": "the count goes negative and stays there"
+        }
+      ]
+    },
+    {
+      "name": "panel-sizes",
+      "columns": 2,
+      "cells": [
+        {
+          "shot": "size-64x32",
+          "label": "64 x 32"
+        },
+        {
+          "shot": "size-128x32",
+          "label": "128 x 32"
+        },
+        {
+          "shot": "size-128x64",
+          "label": "128 x 64"
+        },
+        {
+          "shot": "size-256x32",
+          "label": "256 x 32"
+        }
+      ]
+    }
+  ]
+}

plugins.json

@@ -678,10 +678,10 @@
       "plugin_path": "plugins/olympics",
       "stars": 0,
       "downloads": 0,
-      "last_updated": "2026-05-15",
+      "last_updated": "2026-09-03",
       "verified": true,
       "screenshot": "",
-      "latest_version": "2.0.1"
+      "latest_version": "2.0.2"
     },
     {
       "id": "pga-tour-leaderboard",

plugins/olympics/README.md

@@ -13,6 +13,13 @@
 
 # Olympics Countdown Plugin
 
+![The countdown on a 128x32 panel: the Olympic rings on the left, the day count
+and "DAYS UNTIL WINTER OLYMPICS" on the right](../../docs/assets/olympics/hero.png)
+
+*Every image in this README is real plugin output, rendered at the true panel
+size with the clock pinned, so it reproduces exactly — including the clipped
+`DAYS UNTI` described under [Known problems](#known-problems).*
+
 A LEDMatrix plugin that displays a countdown to the next Olympics (summer or winter) with an Olympics logo. Once the Olympics starts, it automatically switches to countdown to the closing ceremony.
 
 Screenshot Preview:
@@ -58,45 +65,113 @@ Screenshot Preview:
 
 ## Configuration
 
-The plugin supports the following configuration options:
+Settings live in the plugin's tab in the web UI and in `config/config.json`
+under `olympics`. The schema sets `additionalProperties: false`, so a key that
+is not listed below will be **rejected**, not ignored. The full schema is
+[`config_schema.json`](config_schema.json).
+
+### Basics
+
+| Key | Default | Notes |
+|---|---|---|
+| `enabled` | `false` | Enable or disable the Olympics plugin. |
+| `display_duration` | `30` | How long to display the plugin in seconds (switch mode) (5–300). |
+| `update_interval` | `300` | How often to fetch fresh data in seconds (default: 5 minutes) (60–3600). |
+| `timezone` | `"UTC"` | Timezone for event times (IANA format, e.g., 'America/New_York'). |
+| `section_duration` | `10` | How long to show each section (medals, events, results) in switch mode (3–60). |
+| `vegas_mode` | `"scroll"` | Vegas display mode: scroll (continuous), fixed (static block), static (pauses scroll) — one of `scroll`, `fixed`, `static`. |
+| `text_color` | `[255, 255, 255]` | RGB color for text [R, G, B] (default: white). |
+
+### Which sections appear
 
-### Basic Settings
+| Key | Default | Notes |
+|---|---|---|
+| `show_medals` | `true` | Show medal count section. |
+| `show_schedule` | `true` | Show upcoming events section. |
+| `show_results` | `true` | Show recent results section. |
+| `medal_race_enabled` | `true` | Enable medal race comparison between countries. |
+| `live_alerts_enabled` | `true` | Enable priority alerts for live medal events. |
 
-- `enabled` (boolean, default: `false`): Enable or disable the plugin
-- `display_duration` (number, default: `15`): How long to display the countdown in seconds (1-300)
-- `update_interval` (integer, default: `3600`): How often to update the countdown in seconds (60-86400). Default is 1 hour since the countdown changes daily.
+### What goes in them
 
-### Appearance
+| Key | Default | Notes |
+|---|---|---|
+| `top_countries_count` | `5` | Number of top countries to display by medal count (1–20). |
+| `additional_countries` | *(empty)* | Country codes to always show (ISO 3166-1 alpha-3, e.g., ['USA', 'CAN']). |
+| `rival_countries` | *(empty)* | Rival countries for medal race comparison. |
+| `sport_filters` | *(empty)* | Filter events to specific sports (empty = all sports). |
+| `upcoming_events_count` | `5` | Maximum number of upcoming events to display (1–20). |
+| `recent_results_count` | `5` | Maximum number of recent results to display (1–20). |
 
-- `text_color` (array, default: `[255, 255, 255]`): RGB color for the countdown text (default: white)
-- `logo_size` (integer, optional): Size of the Olympics logo in pixels (8-64). If not specified, size is auto-calculated based on display height.
+### Notifications
 
-### Transitions
+| Key | Default | Notes |
+|---|---|---|
+| `notifications_enabled` | `false` | Enable webhook notifications for medal wins, records, and live finals. |
+| `favorite_countries` | *(empty)* | Countries to receive notifications for (ISO 3166-1 alpha-3, e.g., ['USA', 'CAN']). |
+| `webhooks` | *(empty)* | Webhook endpoints for notifications. |
 
-- `transition` (object): Transition configuration
-  - `type` (string): Transition type - `redraw`, `fade`, `slide`, `wipe`, `dissolve`, `pixelate` (default: `redraw`)
-  - `speed` (integer): Transition speed 1-10 (default: `2`)
-  - `enabled` (boolean): Enable transitions (default: `true`)
+### Settings that do nothing
 
-### Example Configuration
+These four are in the schema and in the web UI form, but no code in the plugin
+reads them. Changing them has no effect.
+
+| Key | Default | Notes |
+|---|---|---|
+| `transition.type` | `"redraw"` | Not implemented. The schema offers `redraw`, `fade`, `slide`, `wipe`, `dissolve` and `pixelate`; none of them do anything. |
+| `transition.speed` | `2` | Not implemented. |
+| `transition.enabled` | `true` | Not implemented. |
+| `high_performance_transitions` | `false` | Not implemented. |
+
+The LEDMatrix core implements no display transitions, and four other plugins
+declare the same dead block — tracked in
+[issue #381](https://github.com/ChuckBuilds/ledmatrix-plugins/issues/381).
+
+
+### Example
 
 ```json
 {
   "olympics": {
     "enabled": true,
-    "display_duration": 20,
-    "update_interval": 3600,
-    "text_color": [255, 255, 255],
-    "logo_size": 24,
-    "transition": {
-      "type": "fade",
-      "speed": 3,
-      "enabled": true
-    }
+    "display_duration": 30,
+    "top_countries_count": 5,
+    "rival_countries": ["USA", "CHN"],
+    "sport_filters": ["Alpine Skiing", "Figure Skating"]
   }
 }
 ```
 
+## Known problems
+
+Two defects on the countdown screen, tracked in
+[issue #410](https://github.com/ChuckBuilds/ledmatrix-plugins/issues/410).
+
+**The countdown is currently negative.** The plugin carries one hardcoded
+Games — Milano Cortina, opening 6 February 2026 — and the day count is a plain
+difference with no floor and nothing to roll on to. Since those Games closed,
+every install has been counting down past zero:
+
+![Before and after the Games](../../docs/assets/olympics/countdown-state.png)
+
+**`DAYS UNTIL` is clipped below 256px.** The lines are centred in the right
+half of the panel, and at the default font the label is wider than that half,
+so it loses its last characters. Only a 256-wide panel fits it:
+
+![The countdown on four panel sizes](../../docs/assets/olympics/panel-sizes.png)
+
+At 64x32 the text also overlaps the rings.
+
+This is not a subtle clip: `check_plugin.py` fails six of its eight panel
+sizes on it, and the two that pass are the 256-wide ones.
+
+```
+[FAIL]   64x32  olympics overflow bbox=(64, 8, 87, 31)
+[FAIL]  128x32  olympics overflow bbox=(129, 8, 135, 15)
+[PASS]  256x32  olympics
+[PASS] 256x128  olympics
+```
+
 ## Display Behavior
 
 ### Countdown Display
@@ -160,7 +235,11 @@ If the logo image doesn't appear:
 ### Text Not Fitting
 
 - The plugin automatically adjusts text size and layout based on display dimensions
-- If text still doesn't fit, reduce `logo_size` in configuration
+- There is no `logo_size` setting. Earlier versions of this README suggested
+  reducing one; the schema has no such key and sets `additionalProperties:
+  false`, so adding it makes the configuration invalid. The label clipping is
+  [issue #410](https://github.com/ChuckBuilds/ledmatrix-plugins/issues/410),
+  and a 256-wide panel is the only current workaround
 - The plugin automatically adjusts layout based on display dimensions
 
 ## Development

plugins/olympics/manifest.json

@@ -1,7 +1,7 @@
 {
   "id": "olympics",
   "name": "Olympics",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "author": "ChuckBuilds",
   "description": "Enhanced Olympics plugin with live medal counts, upcoming events, results, and countdown. Supports Vegas scroll mode and regular display mode.",
   "category": "sports",
@@ -37,6 +37,12 @@
     "country_tracking": true
   },
   "versions": [
+    {
+      "version": "2.0.2",
+      "released": "2026-09-03",
+      "notes": "Documentation. The configuration section listed 7 of the 25 settings, and four of the seven it did list were wrong: display_duration and update_interval gave defaults of 15 and 3600 where the schema says 30 and 300; logo_size does not exist in the schema at all, and because additionalProperties is false a config containing it is rejected rather than ignored; and the Transitions section documented a block no code reads. All 25 settings are now covered, with the four dead ones marked. Records two defects on the countdown screen (#410): the day count has gone negative since Milano Cortina closed, because the plugin carries one hardcoded Games and no roll-forward, and DAYS UNTIL is clipped on every panel narrower than 256, which fails six of the harness's eight sizes on main. Adds real rendered screenshots.",
+      "ledmatrix_min": "2.0.0"
+    },
     {
       "released": "2026-05-15",
       "version": "2.0.1",
@@ -54,7 +60,7 @@
       "ledmatrix_min_version": "2.0.0"
     }
   ],
-  "last_updated": "2026-05-15",
+  "last_updated": "2026-09-03",
   "stars": 0,
   "downloads": 0,
   "verified": true,