2 files changed, 118 insertions, 5 deletions
diff --git a/docs/building.md b/docs/building.md
new file mode 100644
index 0000000..e20bcd3
--- /dev/null
+++ b/docs/building.md
@@ -0,0 +1,113 @@
+# Building LabUI from Source
+
+Produces a standalone `dist/LabUI/` directory (onedir, not onefile — required for tufup's per-file update patching).
+
+## Prerequisites
+
+Python 3.10+ and the dev requirements:
+
+```bash
+pip install -r requirements.txt
+pip install -r requirements-dev.txt
+```
+
+`requirements-dev.txt` adds PyInstaller and tufup on top of the runtime deps.
+
+## First-time setup — TUF repository
+
+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).
+
+```bash
+python scripts/release/repo_init.py
+```
+
+This generates:
+
+- `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`.
+
+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):
+
+```bash
+pyinstaller labui.spec
+```
+
+## Building a release
+
+### 1. Bump the version
+
+Edit `core/version.py`:
+
+```python
+__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.
+
+### 2. Build the executable
+
+```bash
+pyinstaller labui.spec
+```
+
+Output: `dist/LabUI/LabUI` (Linux/macOS) or `dist/LabUI/LabUI.exe` (Windows).
+
+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)
+
+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.
+
+### 3. Sign the release target
+
+```bash
+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/`.
+
+### 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.
+
+The app's updater always points at `.../releases/download/updates/`, so the tag must stay constant across versions.
+
+Optionally create a separate human-facing release with a changelog under a version tag (e.g. `v1.2.3`).
+
+### 5. Verify
+
+Launch a previous installed version → 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:
+
+```bash
+python -m tufup sign snapshot scripts/release/keystore
+python -m tufup sign timestamp scripts/release/keystore
+```
+
+Run from the repo root. Re-upload the resulting files to the `updates` release.
+
+## What's bundled vs. external
+
+| Item | Bundled in exe? | Notes |
+|------|----------------|-------|
+| Python runtime | Yes | PyInstaller includes it |
+| PyQt6 / pyqtgraph / numpy | Yes | |
+| 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 |
+| `opencv-python` | No | optional; only needed if a plugin requires it (vendor it in the plugin zip) |
+
+## Troubleshooting
+
+**`ModuleNotFoundError` at launch** — a hidden import PyInstaller missed. Add it to `hiddenimports` in `labui.spec` and rebuild.
+
+**Plugin not loading in built app** — plugins are not bundled; the user must install them via Settings → Plugins. If the plugin loads but fails silently, check that its `vendor/` folder contains all required packages, or that the user has pip-installed them (they land in `~/.labui/plugin_packages/`).
+
+**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.
diff --git a/docs/plugin-development.md b/docs/plugin-development.md
index b0c3a63..8722376 100644
--- a/docs/plugin-development.md
+++ b/docs/plugin-development.md
@@ -1,4 +1,4 @@
-# LabDAQ Plugin Development Guide
+# LabUI Plugin Development Guide
 
 Plugins live under `plugins/` as self-contained directories. The app discovers them automatically; the user enables or disables them in **Settings → Plugins**. A disabled plugin leaves zero trace in the UI.
 
@@ -287,7 +287,7 @@ The widget is created once when the plugin loads. Apply changes immediately (no
 
 ### 5.5 Profile persistence
 
-`.labdaq` profiles save the **enabled plugin list** automatically — loading a profile enables/disables plugins to match the saved state. Per-plugin configuration state is also saved if you implement these two methods.
+`.labui` profiles save the **enabled plugin list** automatically — loading a profile enables/disables plugins to match the saved state. Per-plugin configuration state is also saved if you implement these two methods.
 
 ```python
 def get_save_state(self) -> dict:
@@ -436,7 +436,7 @@ This plugin adds a sine-wave virtual channel and a toolbar button to toggle a di
   "name":        "Sine Demo",
   "version":     "1.0.0",
   "description": "Virtual sine-wave channel for testing.",
-  "author":      "LabDAQ",
+  "author":      "LabUI",
   "entry_point": "plugin.SineDemoPlugin"
 }
 ```
@@ -537,10 +537,10 @@ Import Qt widgets inside methods or inside `on_load`. This avoids import errors
 Stop background threads (`_running = False; _thread.join()`), disconnect signals, close windows. The app calls `on_unload()` both on user disable and on application close.
 
 **Filter `__init__` params must be JSON-serialisable.**
-They are written into `.labdaq` profiles via `to_dict()` and reconstructed via `filter_from_dict()`. Stick to `int`, `float`, `str`, `bool`.
+They are written into `.labui` profiles via `to_dict()` and reconstructed via `filter_from_dict()`. Stick to `int`, `float`, `str`, `bool`.
 
 **Profiles enable and disable plugins.**
-Loading a `.labdaq` profile reconciles plugin state: plugins not in the profile's enabled list are disabled, plugins in the list are enabled. `apply_save_state` is called after the plugin is loaded. `plugins/enabled.json` is updated to match.
+Loading a `.labui` profile reconciles plugin state: plugins not in the profile's enabled list are disabled, plugins in the list are enabled. `apply_save_state` is called after the plugin is loaded. `plugins/enabled.json` is updated to match.
 
 **Enabled state persists across restarts.**
 `plugins/enabled.json` is written every time a toggle changes. Delete it to reset all plugins to disabled.