feat(update): stable/beta update channel; stable follows release tags (#684)

Adds auto_update.channel: stable follows the newest vX.Y.Z release tag
(detached HEAD; pre-releases and other tags ignored), beta follows main as
before. Nothing ever moves a device backwards: a checkout newer than the
newest release keeps following main (or stays put when detached) until a
release contains its commit. Legacy configs migrate to stable when they
reach a release. Update Code, the weekly updater's preflight, and the
verifier's rollback (back to old_ref: branch or detached release) all
honour the channel. General tab Update Channel select, GET/POST
/api/v3/system/update-channel, release-aware Overview banner and Tools git
panel. New installs default to stable.

Rig fix (ledpi): /system/check-update reports update_available: false when
the channel's action is none (a detached HEAD newer than the newest
release), matching Update Code; the Tools panel no longer calls every
detached HEAD "a release".

Merged with main through #687 (heartbeat verifier, #683 login, #688
plugin_catalog, #685 Tailwind build).

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

docs/ARCHITECTURE.md

@@ -336,8 +336,19 @@ everything else through `_reinstall_with_rollback()`.
 - **Update Code** on the Overview tab and the automatic updater both call
   `perform_core_update()` in
   [`api_v3/system.py`](../web_interface/blueprints/api_v3/system.py):
-  `git pull --rebase`, reinstall changed requirement files, report whether a
-  restart is needed.
+  fetch branches and tags, move the checkout for the update channel, reinstall
+  changed requirement files, report whether a restart is needed.
+- **Update channels** (`auto_update.channel`):
+  [`web_interface/update_channel.py`](../web_interface/update_channel.py)
+  decides the move. `stable` checks out the newest `vX.Y.Z` tag (detached
+  HEAD) when it contains the current commit; `beta` is
+  `git pull --rebase --autostash` on the current branch, and leaves a
+  detached release for `main` first. A stable device newer than the newest
+  release keeps pulling `main` until a release contains its commit, so no
+  update ever moves backwards; a config without the key is written as
+  `stable` once the device reaches a release. Checkouts carry uncommitted
+  edits across with `git stash create`/`apply`, and keep them in the stash
+  list if they no longer apply.
 - **Automatic updates** (`auto_update.enabled`, off by default):
   `AutoUpdater` in [`web_interface/auto_update.py`](../web_interface/auto_update.py)
   runs in the web process, checks every 30 minutes, and updates at most
@@ -350,7 +361,9 @@ everything else through `_reinstall_with_rollback()`.
   both services, waits for the web API to answer and the display service to
   stay up -- and, when the display wrote a heartbeat before the update, to
   keep one fresh from the restarted process (see Liveness) -- and on failure
-  resets to the previous commit and restarts again.
+  returns to where HEAD was (the branch, or detached on the previous
+  release; `old_ref` in the pending file), resets to the previous commit
+  and restarts again.
   Plugin updates run only after a verified core update. State is in
   `data/auto_update_state.json` and `data/auto_update_pending.json`.
 - **Startup validator.** `StartupValidator`

docs/CONFIG_REFERENCE.md

@@ -17,6 +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` |
 | `auto_update.enabled` | bool, `false` | Weekly automatic updates: LEDMatrix code first (health-checked, rolled back on failure), then installed plugins. Toggle in the General tab or install with `first_time_install.sh --enable-auto-update` | `web_interface/auto_update.py`, `src/auto_update_setup.py` (`is_enabled()`) |
+| `auto_update.channel` | `"stable"` or `"beta"`, `"stable"` (template) | What Update Code and the weekly update install. `stable`: the newest `vX.Y.Z` release tag (pre-releases ignored), checked out with a detached HEAD. `beta`: `main`. Never moves a device backwards: one newer than the newest release keeps following `main` until a release contains its commit. Missing (configs from before channels) behaves like `stable` and is saved as `stable` once the device is on a release. General tab, Update Channel | `web_interface/update_channel.py` (`resolve()`) |
 | `timezone` | string, `"America/New_York"` | IANA timezone for schedules and displays | `ConfigManager.get_timezone()` |
 | `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. Starlark (Tidbyt) apps get the same treatment: a `Location` field left blank on the app renders at this city (geocoded once via Open-Meteo, coordinates cached permanently) instead of the app author's default, which is usually San Francisco. If the city can't be looked up (no match, or the geocoder is unreachable; retried after 30 minutes), the app keeps its own default. | `SchemaManager.apply_device_location()`, then plugins via merged config; `src/device_location.py` for Starlark apps |

docs/GETTING_STARTED.md

@@ -240,6 +240,22 @@ The fastest way to verify a plugin works without waiting for the rotation:
 - Install community plugins straight from a GitHub URL via
   **Install from GitHub** on the same tab.
 
+### Keep LEDMatrix Up to Date
+
+- **Update Code** on the **Overview** tab installs the newest version, and a
+  banner at the top of the page says when one is available.
+- **General → Automatic Updates** does it once a week, overnight, with a
+  health check that undoes an update that breaks the device.
+- **General → Update Channel** picks which version that is. **Stable** (the
+  default) installs releases, which have been tested and have release
+  notes. **Beta** installs the newest code as soon as it is written, before
+  it is released: fixes arrive sooner, and so do new problems.
+- Switching to Stable never installs an older version than the one you
+  have. If your device is already newer than the latest release (which is
+  normal if it was set up or updated from the newest code), it keeps
+  getting the newest code until the next release includes it, then follows
+  releases from there. The General tab says when this is the case.
+
 ### Enable Advanced Features
 
 **Vegas Scroll Mode:**

docs/REST_API_REFERENCE.md

@@ -1485,20 +1485,59 @@ Get LEDMatrix repository version.
 
 **GET** `/api/v3/system/check-update`
 
-Whether `origin/main` has commits the checkout lacks. Cached briefly.
-Fields at the top level (no envelope):
+Whether newer code is available on this device's update channel. On
+`stable` that is a newer release tag than the checkout (`target_version`
+names it); on `beta`, and on `stable` while it waits on a branch for a
+release that contains the current commit, it is commits on `origin/main`
+the checkout lacks. A detached checkout newer than the newest release is
+never offered an update: Update Code leaves it where it is until a release
+includes it, and `channel_message` says so in the General tab's words.
+Cached briefly. Fields at the top level (no envelope):
 
 ```json
 {
   "update_available": true,
   "remote_sha": "abc123...",
-  "commits_behind": 3
+  "commits_behind": 3,
+  "target_version": "v3.8.0",
+  "channel": "stable",
+  "configured_channel": "stable",
+  "waiting": false,
+  "newest_release": "v3.8.0",
+  "current_release": null,
+  "channel_message": "Stable: release v3.8.0 is available."
 }
 ```
 
 When git cannot run the check, the response also carries
 `"check_failed": true` and an `error` explaining why.
 
+### Update Channel
+
+**GET** `/api/v3/system/update-channel`
+
+The update channel and what the next Update Code or weekly update would do
+(in `data`): `configured` (`"stable"`, `"beta"` or `null` for a config from
+before channels), `channel` (the one in effect), `waiting` (stable, but the
+device is newer than the newest release, so it follows `main` for now),
+`action` (`none`, `checkout_tag`, `pull` or `switch_to_beta`),
+`newest_release`, `current_release`, `branch` (`""` when on a release tag),
+`message`. Reads local refs; `?fetch=1` fetches from origin first.
+
+**POST** `/api/v3/system/update-channel`
+
+```json
+{
+  "channel": "beta"
+}
+```
+
+Saves `auto_update.channel`. The next update applies it; switching to
+`stable` never installs an older version than the one running, and the
+`message` says when the device keeps following `main` until a newer release.
+400 for anything but `stable` or `beta`. The General tab form also accepts
+`auto_update_channel` on `POST /api/v3/config/main`.
+
 ### Automatic Update Status
 
 **GET** `/api/v3/system/auto-update`
@@ -1524,7 +1563,9 @@ Hide the current automatic-update alert until a new one replaces it.
 
 Branch, dirty state, recent commits and remote for the Tools tab. Fields at
 the top level: `branch`, `dirty`, `status`, `recent_commits`, `remote_url`
-(credentials scrubbed), `upstream`, `can_pull`.
+(credentials scrubbed), `upstream`, `can_pull`, and for the update channel
+`detached`, `version` (`git describe`), `current_release` (the release tag
+HEAD is exactly on, else `null`) and `channel_message` (detached only).
 
 ### Git Branches
 

docs/TROUBLESHOOTING.md

@@ -295,6 +295,42 @@ sudo systemctl cat ledmatrix-web | grep User
 
 ---
 
+#### Issue: Updates and the update channel
+
+**Symptoms:**
+- The General tab says "Stable: this device runs code newer than the newest
+  release ... keeps following main"
+- Tools shows a version such as `v3.8.0` instead of a branch name, or `git
+  status` over SSH says `HEAD detached at v3.8.0`
+- Update Code says "already up to date" while GitHub's `main` has newer commits
+
+**Explanation:** these are the Stable update channel working as intended
+(`auto_update.channel`, General → Update Channel). Stable installs the
+newest release tag, which git checks out without a branch ("detached
+HEAD"); that is normal and every update path handles it. Stable never
+installs an older version than the one running, so a device that is ahead of
+the newest release keeps following `main` until a release includes its
+commit, then switches to releases on its own.
+
+**Solutions:**
+
+1. **Want the newest code instead?** Set Update Channel to **Beta** and click
+   Update Code. The device leaves the release for `main` and pulls it.
+   Or from SSH:
+   ```bash
+   curl -X POST http://localhost:5000/api/v3/system/update-channel \
+        -H 'Content-Type: application/json' -d '{"channel": "beta"}'
+   ```
+2. **See what the next update will do:**
+   ```bash
+   curl 'http://localhost:5000/api/v3/system/update-channel?fetch=1'
+   ```
+3. **Local changes after a channel switch:** edits that no longer fit the new
+   version are kept in the git stash rather than lost; `git stash list`
+   shows them as "LEDMatrix autostash before update".
+
+---
+
 ### WiFi & AP Mode Issues
 
 #### AP Mode Not Activating
@@ -1010,6 +1046,11 @@ git reset --hard HEAD~1
 # Or rollback to specific commit
 git reset --hard <commit-hash>
 
+# On the Stable update channel HEAD is a release tag, not a branch:
+# go back to an earlier release instead (the next update moves forward again)
+git tag --list 'v*' --sort=-v:refname | head
+git checkout --detach v3.7.0
+
 # Restart all services
 sudo systemctl restart ledmatrix
 sudo systemctl restart ledmatrix-web

docs/WEB_INTERFACE_GUIDE.md

@@ -78,7 +78,9 @@ The Overview tab provides at-a-glance information and quick actions:
 - **Start Display** / **Stop Display** — control the display service
 - **Restart Display Service** — apply configuration changes
 - **Restart Web Service** — restart the web UI itself
-- **Update Code** — `git pull` the latest version (stashes local changes)
+- **Update Code** — update to the newest version on the update channel (the
+  newest release on Stable, the newest code on `main` on Beta; stashes local
+  changes). The channel is set on the General tab.
 - **Reboot System** / **Shutdown System** — confirm-gated power controls
 
 **Display Preview:**
@@ -90,6 +92,11 @@ The Overview tab provides at-a-glance information and quick actions:
 
 Configure basic system settings:
 
+- **Automatic Updates** — weekly updates with a health check and rollback
+- **Update Channel** — **Stable** (default) installs releases; **Beta**
+  installs the newest code on `main` before it is released. Switching to
+  Stable never installs an older version: a device ahead of the newest
+  release keeps following `main` until a release includes it
 - **Timezone** — used by all time/date displays
 - **Location** — city/state/country for weather and other location-aware
   plugins