Finish multi-platform release restructuring (previous commit was incomplete)

git add silently staged nothing from the previous attempt because one
pathspec in that batch (scripts/release/repository, already moved) no
longer existed — only the .gitignore-adjacent renames landed. This
commit adds what was actually meant to go in:

- core/updater.py: releases/download/updates-<platform>/ instead of a
  single shared updates/ tag.
- labui.spec: bundles root.json from this platform's own tree.
- scripts/release/repo_init.py, repo_release.py: auto-detect platform,
  operate inside scripts/release/<platform>/.
- .gitignore: per-platform ignore rules (previous commit only carried
  the file renames, not this).
- docs/building.md, scripts/release/README.md: rewritten for the
  per-platform flow.
- Also picks up pre-existing local TUF re-signing (new snapshot/
  timestamp signatures, bumped expiry/version) that was sitting
  uncommitted before this restructuring started.

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

1 files changed, 28 insertions, 22 deletions

diff --git a/docs/building.md b/docs/building.md
index e20bcd3..bdf9ed0 100644
--- a/docs/building.md
+++ b/docs/building.md
@@ -2,6 +2,8 @@
 
 Produces a standalone `dist/LabUI/` directory (onedir, not onefile — required for tufup's per-file update patching).
 
+PyInstaller does not cross-compile — build on the same OS you're targeting. For Windows, build on Windows. For Linux, build on Linux (WSL2 works fine if your day-to-day machine is Windows — it produces a real Linux ELF binary, no cross-compilation involved). Each OS gets its own independent TUF signing setup (see below) and its own release tag, since a Windows build and a Linux build of the same version are different byte-for-byte archives.
+
 ## Prerequisites
 
 Python 3.10+ and the dev requirements:
@@ -13,26 +15,26 @@ pip install -r requirements-dev.txt
 
 `requirements-dev.txt` adds PyInstaller and tufup on top of the runtime deps.
 
-## First-time setup — TUF repository
+## First-time setup — TUF repository (once per platform)
 
-Skip this if the `scripts/release/keystore/` directory already exists (i.e. someone else on the team has already initialised the repo and shared the keystore out-of-band).
+Skip this for a given platform if `scripts/release/<platform>/keystore/` already exists (i.e. someone else on the team has already initialised that platform's repo and shared the keystore out-of-band). `<platform>` is `win`, `linux`, or `mac` — `repo_init.py` picks it automatically based on the OS you run it on.
 
 ```bash
 python scripts/release/repo_init.py
 ```
 
-This generates:
+This generates, under `scripts/release/<platform>/`:
 
-- `scripts/release/keystore/` — private + public keys for the TUF root/targets/snapshot/timestamp roles. **Back this up somewhere private outside the repo. Losing the root key means existing installs can never receive trusted updates.**
-- `scripts/release/repository/` — initial signed TUF metadata, including `root.json`.
+- `keystore/` — private + public keys for the TUF root/targets/snapshot/timestamp roles for *this platform*. **Back this up somewhere private outside the repo. Losing a platform's root key means that platform's existing installs can never receive trusted updates again** (other platforms are unaffected — keys are fully independent per platform).
+- `repository/` — initial signed TUF metadata for this platform, including `root.json`.
 
-After init, build once more so the freshly-generated `root.json` gets bundled into the app (the `.spec` file only includes it if it already exists):
+After init, build once more so the freshly-generated `root.json` gets bundled into the app (the `.spec` file only includes it if it already exists, and reads it from this same platform's tree):
 
 ```bash
 pyinstaller labui.spec
 ```
 
-## Building a release
+## Building a release (repeat per platform, on that platform)
 
 ### 1. Bump the version
 
@@ -42,7 +44,7 @@ Edit `core/version.py`:
 __version__ = "1.2.3"
 ```
 
-This single value is read by the auto-updater at runtime (`core/updater.py`) and by the release script when signing the new target.
+This single value is read by the auto-updater at runtime (`core/updater.py`) and by the release script when signing the new target. Use the same version number across all platforms for one release, even though each is built/signed/published as a separate step.
 
 ### 2. Build the executable
 
@@ -50,11 +52,11 @@ This single value is read by the auto-updater at runtime (`core/updater.py`) and
 pyinstaller labui.spec
 ```
 
-Output: `dist/LabUI/LabUI` (Linux/macOS) or `dist/LabUI/LabUI.exe` (Windows).
+Output: `dist/LabUI/LabUI` (Linux/macOS) or `dist/LabUI/LabUI.exe` (Windows) — whichever OS you're currently running on.
 
 The build bundles:
 - `ui/style_dark.qss` and `ui/style_light.qss`
-- `scripts/release/repository/metadata/root.json` (if present — enables trusted updates on fresh installs)
+- `scripts/release/<platform>/repository/metadata/root.json` (if present — enables trusted updates on fresh installs; `<platform>` auto-detected from the OS running PyInstaller)
 
 Plugins are **not bundled**. They are installed at runtime by the user via **Settings → Plugins → Install Plugin…**. Installed plugins and their enabled state live in `~/.labui/plugins/`. Plugin pip dependencies (for machines without Python) land in `~/.labui/plugin_packages/`, which is added to `sys.path` at startup.
 
@@ -64,30 +66,32 @@ Plugins are **not bundled**. They are installed at runtime by the user via **Set
 python scripts/release/repo_release.py
 ```
 
-Creates and signs `scripts/release/repository/targets/labui-<version>.tar.gz` and updates the TUF metadata files in `scripts/release/repository/metadata/`.
+Creates and signs `scripts/release/<platform>/repository/targets/labui-<version>.tar.gz` and updates the TUF metadata files in `scripts/release/<platform>/repository/metadata/`.
 
 ### 4. Publish to GitHub
 
-Upload every file from `scripts/release/repository/metadata/` and `scripts/release/repository/targets/` to the GitHub Release tagged **`updates`** (fixed tag — not a version tag), replacing any same-named files already there.
+Upload every file from `scripts/release/<platform>/repository/metadata/` and `scripts/release/<platform>/repository/targets/` to the GitHub Release tagged **`updates-<platform>`** (e.g. `updates-win`, `updates-linux` — fixed tag per platform, not a version tag), replacing any same-named files already there.
+
+The app's updater always points at `.../releases/download/updates-<platform>/` (platform auto-detected at runtime by `core.updater._platform_key()`), so each platform's tag must stay constant across versions. Don't share one tag across platforms — TUF metadata filenames (`root.json`, `timestamp.json`, ...) aren't platform-prefixed, so one platform's publish would silently overwrite the other's trust root.
 
-The app's updater always points at `.../releases/download/updates/`, so the tag must stay constant across versions.
+A bare `LabUI.exe` does **not** belong on the `updates-<platform>` release — the updater only looks for the TUF metadata + target archive described above; a loose exe there does nothing.
 
-Optionally create a separate human-facing release with a changelog under a version tag (e.g. `v1.2.3`).
+Optionally create a separate human-facing release with a changelog under a version tag (e.g. `v1.2.3`) for people downloading the app for the first time (TUF only handles *updating* an already-installed copy). Since the build is onedir, zip the whole `dist/LabUI/` folder for that release rather than attaching the bare exe — the exe alone won't run without its sibling files. If you support multiple platforms, attach one zip per platform to that same version-tagged release.
 
 ### 5. Verify
 
-Launch a previous installed version → Settings → Check for Updates → confirm it finds and applies the new version.
+Launch a previous installed version of this platform → Settings → Check for Updates → confirm it finds and applies the new version.
 
 ## Re-signing expired metadata
 
-TUF metadata expires even with no new release (`root`: 365 days, others: 90 days). If metadata goes stale before the next release, clients reject it. Re-sign:
+TUF metadata expires even with no new release (`root`: 365 days, others: 90 days) — independently per platform. If metadata goes stale before the next release for a given platform, that platform's clients reject it. Re-sign:
 
 ```bash
-python -m tufup sign snapshot scripts/release/keystore
-python -m tufup sign timestamp scripts/release/keystore
+python -m tufup sign snapshot scripts/release/<platform>/keystore
+python -m tufup sign timestamp scripts/release/<platform>/keystore
 ```
 
-Run from the repo root. Re-upload the resulting files to the `updates` release.
+Run from the repo root, substituting the actual platform directory. Re-upload the resulting files to that platform's `updates-<platform>` release.
 
 ## What's bundled vs. external
 
@@ -98,8 +102,8 @@ Run from the repo root. Re-upload the resulting files to the `updates` release.
 | QSS theme files | Yes | copied from `ui/` |
 | Plugins | No | installed by users into `~/.labui/plugins/` at runtime |
 | Plugin pip deps | No | installed into `~/.labui/plugin_packages/` or vendored inside plugin zip |
-| `root.json` | Yes (if present) | TUF trust bootstrap |
-| `nidaqmx` | No | optional; NI runtime must be installed separately |
+| `root.json` | Yes (if present) | TUF trust bootstrap, this platform's own copy |
+| `nidaqmx` | No | optional; NI runtime is Windows-only, must be installed separately |
 | `opencv-python` | No | optional; only needed if a plugin requires it (vendor it in the plugin zip) |
 
 ## Troubleshooting
@@ -110,4 +114,6 @@ Run from the repo root. Re-upload the resulting files to the `updates` release.
 
 **Plugin dependency not importable after pip install** — the user may need to restart the app so `~/.labui/plugin_packages/` is injected into `sys.path` (this happens in `main.py` at startup).
 
-**`root.json` not bundled** — run `repo_init.py` first (see First-time setup), then rebuild.
+**`root.json` not bundled** — run `repo_init.py` first (see First-time setup), then rebuild, on this same platform.
+
+**Updates work on one platform but not another** — check each platform published to its own `updates-<platform>` tag, not a shared `updates` tag, and that `core.updater._platform_key()`'s mapping (`win`/`mac`/else-`linux`) matches the directory names under `scripts/release/`.