Release 0.0.7: user-local installer + self-update apply

- install.sh: no-root user-local install (private venv + ~/.local/bin launchers
  + desktop entry); --ref <tag> to install a specific release, --uninstall to
  remove; auto-installs the python3-venv prerequisite with consent
- packaging/make-run.sh: build a self-extracting .run installer (makeself)
  bundling the wheel + install.sh; release workflow builds and attaches it
- M13 self-update apply: `rigdoctor update` runs an authenticated pip upgrade
  (rigdoctor[gui] @ git+https://oauth2:<token>@...@<tag>), token scrubbed; GUI
  sidebar "Update to v…" button applies it and prompts to restart
- version 0.0.7, CHANGELOG, docs (M9/M13, ROADMAP, README install section)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.gitea/workflows/release.yml

@@ -27,6 +27,11 @@ jobs:
           python -m pip install --upgrade build
           python -m build
 
+      - name: Build self-extracting installer (.run)
+        run: |
+          (apt-get update && apt-get install -y makeself && sh packaging/make-run.sh) \
+            || echo "makeself unavailable — skipping .run"
+
       - name: Read version
         id: ver
         run: |

CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to RigDoctor are recorded here. Format follows
 (`MAJOR.MINOR.PATCH`, pre-1.0). `__version__` and `pyproject.toml` must match the git
 release tag (so the auto-updater, D18, can compare versions).
 
+## [0.0.7] - 2026-05-21
+### Added
+- **User-local installer** `install.sh` (no root): creates a private venv, links
+  `rigdoctor`/`rigdoctor-gui` into `~/.local/bin`, and adds a desktop entry. Re-run to
+  upgrade; `--uninstall` to remove.
+- **Self-extracting `.run` installer** via `packaging/make-run.sh` (makeself) — one
+  download-and-run executable bundling the wheel + `install.sh`; built and attached to each
+  release by CI.
+- **Self-update apply (M13)**: `rigdoctor update` now installs the newer version via
+  authenticated pip (`rigdoctor[gui] @ git+https://oauth2:<token>@…@<tag>`); the GUI sidebar
+  "Update to v…" button applies it and prompts to restart. Token is scrubbed from output.
+
+## [0.0.6] - 2026-05-21
+### Added
+- **Token-gated updates (M13)**: store a Gitea Personal Access Token, **encrypted in the OS
+  keyring** (Secret Service / GNOME Keyring via `secret-tool`) with a 0600-file fallback.
+  `rigdoctor login` / `logout` / `update [--check]`; GUI **Setup → Update access** panel
+  (token field, "Get a token", backend status) and sidebar states (connect / up-to-date /
+  "Update to v…" / access denied). Updates are gated to accounts on the Gitea server (D18).
+- `libsecret-tools` added to the installer catalog (enables encrypted token storage).
+### Changed
+- D18 update mechanism revised from anonymous public HTTP to **authenticated HTTP (token)** —
+  the Gitea instance requires sign-in for all anonymous access.
+
+## [0.0.5] - 2026-05-21
+### Added
+- **M9 installer (first cut)**: detects distro / package manager / GPU; a catalog of optional
+  components (smartmontools, lm-sensors, dmidecode, pciutils, libnotify) with what each
+  enables; `rigdoctor install [--check] [-y]` installs missing apt packages via pkexec/sudo
+  with consent; GUI **Setup** tab with one-click install. Fixes the "smartmontools missing"
+  gap in the health report.
+- **Update check (M13, check half)**: on GUI launch the sidebar checks the Gitea releases API
+  and shows "up-to-date", an "Update to v…" button if a newer release exists, or "update check
+  unavailable" if the API can't be reached anonymously.
+
+## [0.0.4] - 2026-05-21
+### Added
+- **M4 health report**: scans kernel logs (NVIDIA Xid incl. 79 "fell off the bus", kernel
+  panic, OOM, MCE, PCIe AER, thermal, amdgpu reset), SMART health, NVIDIA driver/library
+  mismatch, journald persistence, and live temps → prioritized plain-language findings with
+  suggested fixes (read-only, D9).
+- CLI `rigdoctor report` (text + `--json`).
+- GUI **Health** tab: runs checks in the background; findings shown as severity-colored cards.
+- Tests for the journal scanner.
+
+## [0.0.3] - 2026-05-21
+### Added
+- Show the app version (`v<version>`) in the GUI sidebar.
+
 ## [0.0.2] - 2026-05-21
 ### Added
 - **M3 crash-capture logger**: crash-safe JSONL (`fsync` per sample), size-based rotation,

README.md

@@ -2,10 +2,10 @@
 
 A **modular diagnostics, monitoring, and health-check toolkit for Linux gamers.**
 
-> **Status:** 🟢 Phase 1 (MVP) in progress. The **sensor core (M1)** and **crash-capture
+> **Status:** 🟢 Phase 1 (MVP) complete. The **sensor core (M1)**, **crash-capture logger
-> logger (M3)** work — `snapshot`/`monitor` read NVIDIA GPU, CPU, memory, and NVMe live, and
+> (M3)**, and **health report (M4)** all work — live `snapshot`/`monitor`, crash-safe `record`
-> `record` captures a crash-safe log with a post-crash report. A desktop GUI (M10) is also
+> with a post-crash report, and `report` to scan logs/SMART/driver for likely causes. A
-> up. Health report (M4) is next. See `docs/ROADMAP.md`.
+> desktop GUI (M10) ties them together (dashboard, recording, health). See `docs/ROADMAP.md`.
 
 ## Why this exists
 
@@ -63,6 +63,21 @@ Full rationale and the still-open questions are in `docs/DECISIONS.md`.
 | `installer/` | Installer / `.deb` packaging (empty until Phase 4) |
 | `tests/` | Tests (stdlib `unittest`) |
 
+## Install (user-local, no root)
+
+RigDoctor installs into a private venv under `~/.local` — no root, self-updating:
+
+```bash
+./install.sh                 # from a source checkout or the self-extracting .run
+./install.sh --ref v0.0.6    # install a specific released tag (needs a token)
+./install.sh --uninstall     # remove it
+```
+
+This adds `rigdoctor` / `rigdoctor-gui` to `~/.local/bin` and a desktop entry. Each release
+also ships a one-file **`.run`** installer (download, `chmod +x`, run). Updates are gated to
+accounts on the Git server (a Personal Access Token); save one via the GUI **Setup → Update
+access** panel or `rigdoctor login`, then `rigdoctor update` (or the sidebar button).
+
 ## Run it (dev)
 
 Stdlib-only, no install needed (target is Python ≥ 3.11; tested on 3.14):
@@ -104,8 +119,8 @@ rigdoctor gui             # or: rigdoctor-gui
 It opens a dark-themed window with sidebar navigation and a **live dashboard** over the
 same sensor core — circular gauges for the headline metrics plus collapsible per-subsystem
 cards (GPU/CPU/memory/storage) with temperature-colored values (icey-blue → green → red).
-The **Logs** section is a full recording page (start/stop, live status, and the post-crash
+The **Logs** and **Health** sections are full pages (recording controls + post-crash report;
-report); Health / Inventory are placeholders until M4 / M5 land.
+and the kernel-log / SMART / driver scan). **Inventory** is a placeholder until M5 lands.
 
 Without the GUI extra, `pip install -e .` gives just the stdlib-only CLI.
 

docs/DECISIONS.md

@@ -152,9 +152,22 @@ reachable from it. This **supersedes the earlier "CLI-first / terminal-first" fr
 - *No change to layering (D2):* the core, CLI, and daemon stay **stdlib-only** and must run
   without Qt. "GUI-first" is about emphasis and front-end parity, not dropping headless support.
 
-### D18 — Auto-update (M13) — *PLANNED 2026-05-21*
+### D18 — Auto-update (M13) — *PLANNED 2026-05-21; mechanism revised 2026-05-21*
 RigDoctor should **check for a newer version on launch and self-update** (new module **M13**).
-**Mechanism (chosen): user-local, no-root self-update from the public repo.**
+**Mechanism (revised): user-local, no-root self-update over authenticated HTTP (token).**
+*Why revised:* the Gitea instance requires sign-in for **all** anonymous access (repo page,
+releases feed, raw, API all 303/403 anonymously), so the original "public HTTP" plan can't
+work. Updates are therefore **gated to people with an account on the Gitea server**, which is
+desirable — access control is delegated to Gitea.
+- *Auth:* each user creates a **Personal Access Token** (scope `read:repository`); RigDoctor
+  stores it at `~/.config/rigdoctor/token` (mode 0600) or reads `RIGDOCTOR_TOKEN`. Requests
+  send `Authorization: token <PAT>`. Finer access = repo visibility/collaborators on Gitea.
+- *Check:* `GET /api/v1/repos/jessey/rigdoctor/releases/latest` with the token; compare tags.
+- *Apply:* `pip install --upgrade "git+https://oauth2:<token>@…/rigdoctor.git@<tag>"` into the
+  user-local venv, then restart (incl. the daemon). No root.
+- *States surfaced:* no-token → "connect to update server"; auth error → "access denied";
+  newer → "Update to v…"; else "up-to-date".
+- *Original (now-superseded) plan was anonymous public HTTP:*
 - *Install model (D8 revised):* primary install is **user-local** (`~/.local`), so the running
   app can replace its own files and update with **no apt, no root, no password prompt**.
 - *Check:* on launch, query the **public Gitea releases API**

docs/MODULES.md

@@ -10,16 +10,16 @@ Status: ⬜ not started · 🟦 designing · 🟨 in progress · ✅ done
 |----|--------|--------|----------|-----------|----------|--------|
 | M1 | Sensor core | Essential | none (nvidia-smi, sysfs) | all (NVIDIA first) | P0 | ⬜ |
 | M3 | Crash-capture logger | Essential | none (opt: smartmontools) | all (NVIDIA first) | P0 | 🟨 |
-| M4 | Health report (log scan) | Essential | none (opt: smartmontools) | all (NVIDIA first) | P0 | ⬜ |
+| M4 | Health report (log scan) | Essential | none (opt: smartmontools) | all (NVIDIA first) | P0 | 🟨 |
 | M2 | Live monitor (TUI) | Monitoring | none (stdlib curses) | all | P1 | ⬜ |
 | M8 | Alerting | Monitoring | libnotify (opt) | all | P2 | ⬜ |
 | M5 | System inventory | Diagnostics | none (opt: lm-sensors, dmidecode) | all | P1 | ⬜ |
 | M6 | Gaming env checks | Diagnostics | none | all | P2 | ⬜ |
 | M10 | Desktop GUI | Desktop UI | **python3-pyside6** | all | P2 | 🟨 |
 | M11 | Tray / menu-bar applet | Desktop UI | **python3-pyside6** (+ AppIndicator on GNOME) | all | P2 | ⬜ |
-| M9 | Installer | (meta) | none | all | P1 | ⬜ |
+| M9 | Installer | (meta) | none | all | P1 | 🟨 |
 | M12 | Session sharing / remote assist | Sharing | none (Tier 3: tmate/sshx) | all | P3 | ⬜ |
-| M13 | Auto-update | (core) | none (stdlib; user-local file swap) | all | P3 | ⬜ |
+| M13 | Auto-update | (core) | none (stdlib; user-local file swap) | all | P3 | 🟨 |
 | ~~M7~~ | ~~Stress / repro~~ | — | — | — | — | ❌ dropped (D7) |
 
 ## Notes per module
@@ -36,7 +36,9 @@ Status: ⬜ not started · 🟦 designing · 🟨 in progress · ✅ done
 - **M4 Health report** — turns scattered logs into a prioritized, plain-language findings
   list with **suggested** fixes (read-only, D9). Reuses M1 for a live snapshot. Also powers
   the **guided diagnostic session** (with M3): pick a game → focused capture → scan →
-  findings (see SPEC §4).
+  findings (see SPEC §4). *Implemented:* journalctl scan (Xid/panic/OOM/MCE/AER/thermal/amdgpu),
+  SMART, NVIDIA driver-mismatch, journald-persistence + live-temp checks; `rigdoctor report`
+  (text/JSON) + GUI Health tab. GPU-firmware verification deferred.
 - **M2 Live monitor** — depends on M1; the terminal "HWMonitor for Linux" face. Stdlib-only.
 - **M5 / M6 Diagnostics** — inventory export + gaming-env checks; M6 flags risky settings and
   suggests the fix command but does not apply it (D9).
@@ -52,14 +54,29 @@ Status: ⬜ not started · 🟦 designing · 🟨 in progress · ✅ done
   action (the guided diagnostic session), plus Open dashboard / Start-Stop recording /
   Snapshot / Quit (D13). Optional; shares the Qt dependency with M10.
 - **M9 Installer** — interactive wizard layered on the `.deb` (D8); apt-first dependency
-  resolution; enables the logger service and trigger mode.
+  resolution; enables the logger service and trigger mode. *Implemented (first cut):* distro/
+  package-manager/GPU detection (`core/sysenv`), an optional-component catalog (`core/catalog`),
+  and dependency install via pkexec/sudo — `rigdoctor install [--check] [-y]` + GUI Setup tab.
+  The **user-local app install** is `install.sh` (private venv + `~/.local/bin` launchers +
+  desktop entry, no root; handles the `python3-venv` prerequisite) plus a self-extracting
+  **`.run`** (makeself, built by CI). *Pending:* config/module selection + `systemd --user`
+  service enable.
 - **M12 Session sharing / remote assist** (D16) — let a helper inspect a user's machine, in
   an escalating ladder: (1) **diagnostic bundle export** (inventory + recent log + report,
   one-way), (2) **live read-only view** over a user-chosen tunnel (Tailscale/cloudflared/SSH,
   no hosted relay), (3) **gated interactive terminal** wrapping tmate/sshx (read-only by
   default; read-write only on explicit consent — a deliberate exception to D9). Per-session
   consent, ephemeral revocable tokens, audit log.
-- **M13 Auto-update** (D18) — *planned.* On launch, check the public Gitea releases API and
+- **M13 Auto-update** (D18) — *check + auth implemented:* updates are **gated to Gitea account
+  holders** via a Personal Access Token, stored **encrypted in the OS keyring** (`secret-tool`)
+  with a 0600-file fallback (`config.load_token`/`save_token`/`token_backend`). `core/updates`
+  queries the releases API with the token; CLI `login`/`logout`/`update`; GUI Setup "Update
+  access" panel + sidebar states. The no-root **self-update apply** is implemented:
+  `rigdoctor update` runs an authenticated `pip install --upgrade "rigdoctor[gui] @
+  git+https://oauth2:<token>@…@<tag>"` into the user-local venv (GUI "Update to v…" button +
+  restart prompt; token scrubbed). Installed via the user-local **`install.sh`** /
+  self-extracting **`.run`** (M9).
+  *Original plan:* On launch, check the public Gitea releases API and
   **self-update a user-local install with no root** (download → verify checksum/signature →
   atomic symlink swap → restart, incl. the daemon). HTTPS-only, version-check-only (no
   telemetry), opt-out-able. Surfaced in the GUI; `rigdoctor update` in the CLI. (`.deb` users

docs/ROADMAP.md

@@ -15,8 +15,8 @@ Ubuntu + NVIDIA first; `.deb` distribution (see `DECISIONS.md`).
 - [x] M3 crash-capture logger (JSONL, fsync per sample, GPU-lost detection, size rotation)
 - [x] Manual trigger mode (`rigdoctor record run/start/stop/status`); `systemd --user`
       service + other trigger modes in Phase 4 (`run` is already the service entrypoint)
-- [ ] M4 health report (Xid/panic/OOM/MCE/AER/thermal scan + driver-mismatch + snapshot,
+- [x] M4 health report (Xid/panic/OOM/MCE/AER/thermal scan + SMART + driver-mismatch +
-      suggested fixes only — D9)
+      journald-persistence + live temps, suggested fixes only — D9; GPU-firmware verify deferred)
 - [x] `record report` post-crash summary (peak temps/power per subsystem, events, last N samples)
 - **Exit criteria:** user can run it during gaming and, after a freeze/black-screen, see the
   last readings + a plausible cause.
@@ -39,15 +39,18 @@ Ubuntu + NVIDIA first; `.deb` distribution (see `DECISIONS.md`).
 - [ ] Logger trigger modes: always-on + game-launch (D12 — wrapper first:
       `rigdoctor wrap %command%` + global Steam compat-tool; zero-config watcher
       (Steam RunningAppID + /proc) and GameMode hook follow)
-- [ ] M9 interactive installer (GPU detection, module menu, apt dependency resolution,
+- [~] M9 interactive installer — *done:* distro/GPU detection + optional-dependency install
-      service enable + trigger-mode pick)
+      (`rigdoctor install`, GUI Setup tab); **user-local `install.sh` + self-extracting `.run`**
+      (no-root venv install, handles python3-venv prereq, CI-built). *Pending:* module-selection
+      config + `systemd --user` service enable + trigger-mode pick.
 - [ ] `.deb` packaging (D8) declaring per-bundle deps incl. python3-pyside6 for Desktop UI
 
 ## Phase 5 — Breadth (later)
 - [ ] AMD GPU support in M1 (Steam Deck / Radeon)
 - [ ] Intel GPU best-effort
-- [ ] M13 auto-update (D18) — launch-time version check + no-root self-update of the
+- [x] M13 auto-update (D18) — launch-time version check (GUI sidebar) + no-root self-update
-      user-local install from the public Gitea releases; GUI prompt + `rigdoctor update`
+      apply (`rigdoctor update` / sidebar button → authenticated pip upgrade), token-gated.
+      Restart-after-update is manual for now.
 - [ ] (Later, separate milestone) Optional auto-apply of suggested fixes behind explicit
       consent — currently out of scope (D9)
 

install.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env sh
+# RigDoctor user-local installer (no root). Creates a private venv, links the
+# `rigdoctor` / `rigdoctor-gui` commands into ~/.local/bin, and adds a desktop
+# entry. Installs from a bundled wheel (the .run installer) or from a source
+# checkout. Re-run to upgrade; `./install.sh --uninstall` to remove.
+set -eu
+
+APP_NAME=rigdoctor
+DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
+VENV="$DATA_HOME/$APP_NAME/venv"
+BIN_DIR="$HOME/.local/bin"
+DESKTOP_DIR="$DATA_HOME/applications"
+DESKTOP_FILE="$DESKTOP_DIR/rigdoctor.desktop"
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+
+uninstall() {
+    echo "Removing RigDoctor user-local install…"
+    rm -rf "$VENV"
+    rm -f "$BIN_DIR/rigdoctor" "$BIN_DIR/rigdoctor-gui" "$DESKTOP_FILE"
+    echo "Done. (Config and logs under ~/.config/rigdoctor and ~/.local/share/rigdoctor were kept.)"
+}
+
+REF=""
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --uninstall) uninstall; exit 0 ;;
+        --ref) REF="${2:-}"; [ -n "$REF" ] || { echo "--ref needs a tag"; exit 1; }; shift 2 ;;
+        -h|--help) echo "Usage: install.sh [--ref <tag>] [--uninstall]"; exit 0 ;;
+        *) echo "Unknown option: $1"; exit 1 ;;
+    esac
+done
+
+PY=python3
+command -v "$PY" >/dev/null 2>&1 || { echo "python3 not found — install Python 3.11+."; exit 1; }
+"$PY" - <<'EOF' || { echo "Python 3.11+ is required."; exit 1; }
+import sys
+sys.exit(0 if sys.version_info >= (3, 11) else 1)
+EOF
+
+# venv support (ensurepip) is required; install python3-venv if it's missing.
+if ! "$PY" -c "import ensurepip" >/dev/null 2>&1; then
+    PYVER=$("$PY" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
+    PKGS="python3-venv python${PYVER}-venv"
+    echo "Python venv support is missing — needs: $PKGS"
+    if command -v pkexec >/dev/null 2>&1; then ESC=pkexec
+    elif command -v sudo >/dev/null 2>&1; then ESC=sudo
+    else ESC=""; fi
+    if [ -n "$ESC" ] && command -v apt-get >/dev/null 2>&1; then
+        echo "Installing $PKGS (you may be prompted for your password)…"
+        "$ESC" sh -c "apt-get update && apt-get install -y $PKGS" \
+            || { echo "Failed. Install manually: sudo apt install $PKGS"; exit 1; }
+    else
+        echo "Install it manually, then re-run: sudo apt install $PKGS"
+        exit 1
+    fi
+fi
+
+# Where to install from: a specific released tag (--ref), a bundled wheel, or source.
+WHEEL=$(ls "$SCRIPT_DIR"/rigdoctor-*.whl 2>/dev/null | head -n1 || true)
+if [ -n "$REF" ]; then
+    CONF="${XDG_CONFIG_HOME:-$HOME/.config}/rigdoctor/token"
+    TOKEN="${RIGDOCTOR_TOKEN:-$(cat "$CONF" 2>/dev/null || true)}"
+    [ -n "$TOKEN" ] || { echo "--ref needs a token (run 'rigdoctor login' or set RIGDOCTOR_TOKEN)."; exit 1; }
+    SRC="rigdoctor[gui] @ git+https://oauth2:$TOKEN@git.jesseyvanofferen.com/jessey/rigdoctor.git@$REF"
+elif [ -n "$WHEEL" ]; then
+    SRC="$WHEEL[gui]"
+elif [ -f "$SCRIPT_DIR/pyproject.toml" ]; then
+    SRC="$SCRIPT_DIR[gui]"
+else
+    echo "No bundled wheel or source found next to the installer."
+    exit 1
+fi
+
+echo "Creating venv at $VENV…"
+"$PY" -m venv "$VENV"
+"$VENV/bin/pip" install --upgrade pip >/dev/null
+echo "Installing RigDoctor (pulls in PySide6 — this can take a minute)…"
+"$VENV/bin/pip" install "$SRC"
+
+mkdir -p "$BIN_DIR"
+ln -sf "$VENV/bin/rigdoctor" "$BIN_DIR/rigdoctor"
+ln -sf "$VENV/bin/rigdoctor-gui" "$BIN_DIR/rigdoctor-gui"
+
+mkdir -p "$DESKTOP_DIR"
+cat > "$DESKTOP_FILE" <<EOF
+[Desktop Entry]
+Type=Application
+Name=RigDoctor
+Comment=Hardware monitoring & crash diagnostics for Linux gamers
+Exec=$VENV/bin/rigdoctor-gui
+Icon=utilities-system-monitor
+Terminal=false
+Categories=System;Monitor;Utility;
+EOF
+
+echo
+echo "RigDoctor $("$VENV/bin/rigdoctor" --version 2>/dev/null | awk '{print $2}') installed."
+echo "  GUI:  rigdoctor-gui   (or find 'RigDoctor' in your app menu)"
+echo "  CLI:  rigdoctor --help"
+case ":$PATH:" in
+    *":$BIN_DIR:"*) ;;
+    *) echo "  Note: add $BIN_DIR to your PATH (a fresh login usually does this).";;
+esac

packaging/make-run.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env sh
+# Build a self-extracting .run installer: bundles the wheel + install.sh so a user
+# can download one file, run it, and get a no-root user-local install.
+#
+# Requires `makeself` (apt install makeself). Run from the repo root.
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+cd "$ROOT"
+
+command -v makeself >/dev/null 2>&1 || {
+    echo "makeself not found. Install it: sudo apt install makeself"
+    exit 1
+}
+
+VERSION=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+mkdir -p dist
+
+# Build the wheel if it isn't already in dist/.
+if ! ls dist/rigdoctor-"$VERSION"-py3-none-any.whl >/dev/null 2>&1; then
+    python3 -m build --wheel
+fi
+
+STAGE=$(mktemp -d)
+cp dist/rigdoctor-"$VERSION"-py3-none-any.whl "$STAGE"/
+cp install.sh "$STAGE"/install.sh
+chmod +x "$STAGE/install.sh"
+
+OUT="dist/rigdoctor-$VERSION-installer.run"
+makeself --notemp-suffix "$STAGE" "$OUT" "RigDoctor $VERSION installer" ./install.sh
+rm -rf "$STAGE"
+echo "Built $OUT"
+echo "Run it with:  chmod +x $OUT && ./$OUT"

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rigdoctor"
-version = "0.0.2"
+version = "0.0.7"
 description = "Modular hardware monitoring & crash diagnostics for Linux gamers."
 readme = "README.md"
 requires-python = ">=3.11"

src/rigdoctor/__init__.py

@@ -1,3 +1,3 @@
 """RigDoctor — modular hardware monitoring & crash diagnostics for Linux gamers."""
 
-__version__ = "0.0.2"
+__version__ = "0.0.7"

src/rigdoctor/cli.py

@@ -164,9 +164,130 @@ def cmd_record_report(args) -> int:
     return 0
 
 
+def cmd_install(args) -> int:
+    from .core import installer, sysenv
+
+    print(f"Distro:          {sysenv.distro_name()}")
+    pm = sysenv.package_manager()
+    print(f"Package manager: {pm or 'none (only apt is supported)'}")
+    print(f"GPU:             {', '.join(sysenv.gpu_vendors()) or 'unknown'}\n")
+
+    status = installer.component_status()
+    print("Optional components:")
+    for component, present in status:
+        mark = "✓" if present else "✗"
+        print(f"  [{mark}] {component.name:<22} — {component.enables}")
+        if not present:
+            print(f"        apt: {' '.join(component.apt)}")
+
+    missing = [c for c, present in status if not present]
+    if not missing:
+        print("\nAll optional components are installed. ✔")
+        return 0
+
+    packages = installer.missing_packages(missing)
+    print(f"\nMissing packages: {' '.join(packages)}")
+    if args.check:
+        return 0
+    if pm != "apt":
+        print(f"Automatic install needs apt. Install manually:\n  sudo apt install {' '.join(packages)}")
+        return 1
+    if not args.yes:
+        try:
+            reply = input(f"\nInstall {len(packages)} package(s) now? [y/N] ").strip().lower()
+        except EOFError:
+            reply = "n"
+        if reply not in ("y", "yes"):
+            print("Aborted.")
+            return 1
+
+    print("Installing (you may be prompted for your password)…")
+    rc, out = installer.install_packages(packages)
+    print(out[-2000:])
+    if rc == 0:
+        still = [c.name for c, present in installer.component_status() if not present]
+        print("\nStill missing: " + (", ".join(still) if still else "none ✔"))
+    else:
+        print(f"\nInstall failed (exit {rc}).")
+    return rc
+
+
+def cmd_login(args) -> int:
+    from getpass import getpass
+
+    from .core import updates
+
+    token = args.token
+    if not token:
+        print(f"Create a token (scope read:repository) at: {updates.TOKEN_PAGE}")
+        try:
+            token = getpass("Paste token: ").strip()
+        except (EOFError, KeyboardInterrupt):
+            token = ""
+    if not token:
+        print("No token provided.")
+        return 1
+    config.save_token(token)
+    state, tag = updates.update_state()
+    if state == updates.AUTH:
+        print("Token saved, but the server rejected it (check scope/permissions).")
+        return 1
+    if state in (updates.UP_TO_DATE, updates.AVAILABLE):
+        print(f"Token saved and verified. Latest release: {tag}.")
+        return 0
+    print("Token saved (couldn't reach the server to verify right now).")
+    return 0
+
+
+def cmd_logout(args) -> int:
+    config.clear_token()
+    print("Update token removed.")
+    return 0
+
+
+def cmd_update(args) -> int:
+    from .core import updates
+
+    state, tag = updates.update_state()
+    if state == updates.NO_TOKEN:
+        print("No update token. Run `rigdoctor login` after creating one at:")
+        print(f"  {updates.TOKEN_PAGE}")
+        return 1
+    if state == updates.AUTH:
+        print("The update server rejected your token (check scope/permissions).")
+        return 1
+    if state == updates.NETWORK:
+        print("Couldn't reach the update server.")
+        return 1
+    if state == updates.UP_TO_DATE:
+        print(f"Up to date (v{__version__}).")
+        return 0
+    # AVAILABLE
+    print(f"Update available: {tag}  (current v{__version__}).")
+    if args.check:
+        return 0
+    print(f"Installing {tag}…")
+    rc, out = updates.apply_update(tag)
+    print(out[-2000:])
+    if rc == 0:
+        print(f"\nUpdated to {tag}. Restart RigDoctor to use the new version.")
+        return 0
+    print(f"\nUpdate failed (exit {rc}).")
+    return rc
+
+
 def cmd_report(args) -> int:
-    print("`report` (M4 health report) is not implemented yet — next on the roadmap.")
+    from dataclasses import asdict
-    return 2
+
+    from .core.health import run_health_checks
+    from .render import render_health
+
+    findings = run_health_checks()
+    if args.json:
+        print(json.dumps([asdict(f) for f in findings], indent=2, ensure_ascii=False))
+    else:
+        print(render_health(findings))
+    return 0
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -188,6 +309,20 @@ def build_parser() -> argparse.ArgumentParser:
     sub.add_parser("gui", help="launch the desktop GUI (needs PySide6)").set_defaults(func=cmd_gui)
     sub.add_parser("sources", help="list detected sensor sources").set_defaults(func=cmd_sources)
 
+    inst = sub.add_parser("install", help="set up optional system dependencies (M9)")
+    inst.add_argument("--check", action="store_true", help="report status only; install nothing")
+    inst.add_argument("-y", "--yes", action="store_true", help="install without confirmation")
+    inst.set_defaults(func=cmd_install)
+
+    login = sub.add_parser("login", help="save a Gitea token for updates (M13)")
+    login.add_argument("--token", default=None, help="token (prompted if omitted)")
+    login.set_defaults(func=cmd_login)
+    sub.add_parser("logout", help="remove the saved update token").set_defaults(func=cmd_logout)
+
+    upd = sub.add_parser("update", help="check for / apply a newer version (M13)")
+    upd.add_argument("--check", action="store_true", help="only report, don't apply")
+    upd.set_defaults(func=cmd_update)
+
     rec = sub.add_parser("record", help="crash-capture logger (M3)")
     rec_sub = rec.add_subparsers(dest="record_cmd", required=True)
 
@@ -209,7 +344,9 @@ def build_parser() -> argparse.ArgumentParser:
     report_p.add_argument("--log", default=None, help="path to a capture log")
     report_p.set_defaults(func=cmd_record_report)
 
-    sub.add_parser("report", help="health report (coming soon)").set_defaults(func=cmd_report)
+    rep = sub.add_parser("report", help="health report (M4): scan logs/SMART/driver for issues")
+    rep.add_argument("--json", action="store_true", help="output JSON instead of text")
+    rep.set_defaults(func=cmd_report)
     return p
 
 

src/rigdoctor/config.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import os
+import shutil
+import subprocess
 from pathlib import Path
 
 APP = "rigdoctor"
@@ -25,6 +27,112 @@ STATUS_FILE = STATE_DIR / "recorder.json"
 PID_FILE = STATE_DIR / "recorder.pid"
 SPAWN_LOG = STATE_DIR / "recorder.out"
 
+# Update access token (M13) — gates updates to Gitea account holders (D18).
+# Stored in the OS keyring (Secret Service / GNOME Keyring) via `secret-tool` when
+# available — encrypted at rest, unlocked with the login session — else a 0600 file.
+TOKEN_FILE = CONFIG_DIR / "token"
+_SECRET_ATTRS = ["application", "rigdoctor", "type", "update-token"]
+
+
+def _secret_tool() -> str | None:
+    return shutil.which("secret-tool")
+
+
+def keyring_available() -> bool:
+    """True if an encrypted OS keyring (secret-tool) is usable."""
+    return _secret_tool() is not None
+
+
+def _keyring_store(token: str) -> bool:
+    tool = _secret_tool()
+    if not tool:
+        return False
+    try:
+        proc = subprocess.run(
+            [tool, "store", "--label", "RigDoctor update token", *_SECRET_ATTRS],
+            input=token, text=True, capture_output=True, timeout=20,
+        )
+        return proc.returncode == 0
+    except (subprocess.SubprocessError, OSError):
+        return False
+
+
+def _keyring_lookup() -> str | None:
+    tool = _secret_tool()
+    if not tool:
+        return None
+    try:
+        proc = subprocess.run(
+            [tool, "lookup", *_SECRET_ATTRS], text=True, capture_output=True, timeout=20
+        )
+        if proc.returncode == 0 and proc.stdout.strip():
+            return proc.stdout.strip()
+    except (subprocess.SubprocessError, OSError):
+        pass
+    return None
+
+
+def _keyring_clear() -> None:
+    tool = _secret_tool()
+    if not tool:
+        return
+    try:
+        subprocess.run([tool, "clear", *_SECRET_ATTRS], capture_output=True, timeout=20)
+    except (subprocess.SubprocessError, OSError):
+        pass
+
+
+def load_token() -> str | None:
+    """Token from $RIGDOCTOR_TOKEN, then the OS keyring, then a 0600 file."""
+    env = os.environ.get("RIGDOCTOR_TOKEN")
+    if env and env.strip():
+        return env.strip()
+    from_keyring = _keyring_lookup()
+    if from_keyring:
+        return from_keyring
+    try:
+        token = TOKEN_FILE.read_text().strip()
+        return token or None
+    except OSError:
+        return None
+
+
+def save_token(token: str) -> None:
+    """Save to the OS keyring if possible (encrypted); else a 0600 file."""
+    token = token.strip()
+    if _keyring_store(token):
+        try:  # don't leave a plaintext copy once it's in the keyring
+            TOKEN_FILE.unlink()
+        except OSError:
+            pass
+        return
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    TOKEN_FILE.write_text(token + "\n")
+    try:
+        TOKEN_FILE.chmod(0o600)
+    except OSError:
+        pass
+
+
+def clear_token() -> None:
+    _keyring_clear()
+    try:
+        TOKEN_FILE.unlink()
+    except OSError:
+        pass
+
+
+def token_backend() -> str:
+    """Where the active token lives: 'env' | 'keyring' | 'file' | 'none'."""
+    env = os.environ.get("RIGDOCTOR_TOKEN")
+    if env and env.strip():
+        return "env"
+    if _keyring_lookup() is not None:
+        return "keyring"
+    if TOKEN_FILE.exists():
+        return "file"
+    return "none"
+
 DEFAULTS: dict = {
     "interval": 1.0,           # sampling interval in seconds (default ≤1 Hz — NFR)
     "log_max_bytes": 20_000_000,  # rotate a log segment past this size

src/rigdoctor/core/catalog.py

@@ -0,0 +1,48 @@
+"""Installable component catalog (M9): optional system tools and what they enable.
+
+apt-only (D15). Core monitoring (M1/M3/M4) needs no packages — these are optional
+enrichments the installer can add. Each component is detected by a representative
+command (present == usable).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Component:
+    id: str
+    name: str
+    bundle: str
+    enables: str          # capability unlocked when present
+    apt: tuple[str, ...]  # apt package name(s)
+    command: str          # command used to detect presence
+
+
+COMPONENTS: tuple[Component, ...] = (
+    Component(
+        "smartmontools", "SMART disk health", "Diagnostics",
+        "Disk health (SMART) in the health report (M4)", ("smartmontools",), "smartctl",
+    ),
+    Component(
+        "lm-sensors", "lm-sensors", "Diagnostics",
+        "Extra motherboard / voltage sensors", ("lm-sensors",), "sensors",
+    ),
+    Component(
+        "dmidecode", "dmidecode", "Diagnostics",
+        "Motherboard / BIOS / RAM details for system inventory (M5)", ("dmidecode",), "dmidecode",
+    ),
+    Component(
+        "pciutils", "pciutils", "Diagnostics",
+        "PCIe topology + GPU detection (lspci)", ("pciutils",), "lspci",
+    ),
+    Component(
+        "libnotify", "Desktop notifications", "Monitoring",
+        "Desktop alert notifications (M8)", ("libnotify-bin",), "notify-send",
+    ),
+    Component(
+        "libsecret", "Encrypted token storage", "Updates",
+        "Store the update token in the OS keyring, encrypted (M13)", ("libsecret-tools",), "secret-tool",
+    ),
+)

src/rigdoctor/core/health.py

@@ -0,0 +1,245 @@
+"""Health report (M4): scan kernel logs + SMART + driver/library state into a
+prioritized, plain-language findings list with suggested fixes (read-only, D9).
+
+Stdlib-only. Every check degrades gracefully — a missing tool/permission yields an
+info finding, never an exception.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+CRITICAL = "critical"
+WARNING = "warning"
+INFO = "info"
+OK = "ok"
+_ORDER = {CRITICAL: 0, WARNING: 1, INFO: 2, OK: 3}
+
+
+@dataclass
+class Finding:
+    severity: str   # critical | warning | info | ok
+    category: str   # GPU, Kernel, Memory, Storage, Thermal, Driver, PCIe, Logs
+    title: str
+    detail: str = ""
+    suggestion: str = ""
+
+
+# --- NVIDIA Xid knowledge (the seed crash is Xid 79) --------------------------
+_XID_INFO: dict[int, tuple[str, str]] = {
+    13: (WARNING, "Graphics engine exception (often an app/driver bug or unstable overclock)"),
+    31: (WARNING, "GPU memory page fault (usually a driver or application bug)"),
+    43: (WARNING, "GPU stopped processing a task (application error)"),
+    45: (INFO, "Preemptive channel removal (often a side-effect of another error or a reboot)"),
+    48: (CRITICAL, "Double-bit ECC error — VRAM hardware fault"),
+    62: (CRITICAL, "Internal microcontroller halt (often follows instability)"),
+    79: (CRITICAL, "GPU has fallen off the bus — hardware: power delivery, PCIe link, or thermals"),
+    94: (CRITICAL, "Contained ECC error"),
+    95: (CRITICAL, "Uncontained ECC error"),
+    119: (CRITICAL, "GSP RPC timeout — GPU System Processor hang"),
+    120: (CRITICAL, "GSP error — GPU System Processor fault"),
+}
+_XID_SUGGEST: dict[int, str] = {
+    79: "Check PSU/power cables and reseat the GPU/riser; test a lower power limit "
+        "(`sudo nvidia-smi -pl <watts>`) and capture a session with `rigdoctor record`.",
+    48: "Persistent VRAM ECC errors mean failing memory — RMA the card if it recurs.",
+    119: "GSP hangs are often driver-version specific — try a different driver branch.",
+    120: "GSP errors are often driver-version specific — try a different driver branch.",
+}
+_XID_RE = re.compile(r"Xid(?:\s*\([^)]*\))?:?\s*(\d+)")
+
+
+def scan_journal_text(text: str) -> list[Finding]:
+    """Parse kernel-log text into findings (separated from IO so it's testable)."""
+    lines = text.splitlines()
+    findings: list[Finding] = []
+
+    xids: dict[int, int] = {}
+    for line in lines:
+        if "Xid" in line:
+            m = _XID_RE.search(line)
+            if m:
+                code = int(m.group(1))
+                xids[code] = xids.get(code, 0) + 1
+    for code in sorted(xids):
+        severity, desc = _XID_INFO.get(code, (WARNING, f"NVIDIA GPU error (Xid {code})"))
+        suggest = _XID_SUGGEST.get(code, "Look up this Xid code in NVIDIA's Xid error documentation.")
+        findings.append(Finding(severity, "GPU", f"NVIDIA Xid {code} ×{xids[code]}", desc, suggest))
+
+    oom = sum(1 for ln in lines if "Out of memory" in ln or "oom-kill" in ln or "oom_reaper" in ln)
+    if oom:
+        findings.append(Finding(
+            WARNING, "Memory", f"Out-of-memory kills ×{oom}",
+            "The kernel killed processes to reclaim RAM.",
+            "Close memory-heavy apps, add zram/swap, or investigate a leak.",
+        ))
+
+    if any("Kernel panic" in ln for ln in lines):
+        findings.append(Finding(
+            CRITICAL, "Kernel", "Kernel panic recorded",
+            "The kernel hit an unrecoverable error.",
+            "Note the panic message; review recent driver/kernel updates and hardware.",
+        ))
+
+    if any("mce:" in ln or "Machine check" in ln or "Hardware Error" in ln for ln in lines):
+        findings.append(Finding(
+            CRITICAL, "Hardware", "Machine Check Exception (MCE)",
+            "The CPU reported a hardware error.",
+            "Run memtest86 for RAM, check CPU temps/voltages, and review the MCE detail.",
+        ))
+
+    if any("AER:" in ln or "PCIe Bus Error" in ln or ("pcieport" in ln and "error" in ln.lower()) for ln in lines):
+        findings.append(Finding(
+            WARNING, "PCIe", "PCIe bus errors (AER)",
+            "Correctable/uncorrectable PCIe errors were logged.",
+            "Reseat the device and check risers/cabling; AER storms can precede a GPU drop.",
+        ))
+
+    low = [ln.lower() for ln in lines]
+    if any(("thermal" in ln and ("critical" in ln or "throttl" in ln)) or "temperature above threshold" in ln for ln in low):
+        findings.append(Finding(
+            WARNING, "Thermal", "Thermal events logged",
+            "The system logged thermal throttling / critical-temperature events.",
+            "Improve airflow/cooling and check fan curves; watch live temps on the dashboard.",
+        ))
+
+    if any("amdgpu" in ln and "reset" in ln for ln in low):
+        findings.append(Finding(
+            CRITICAL, "GPU", "AMD GPU reset (amdgpu)",
+            "The AMD GPU was reset after a hang.",
+            "Check power/thermals/driver; capture a session with `rigdoctor record`.",
+        ))
+
+    return findings
+
+
+def _journalctl(args: list[str]) -> str | None:
+    if shutil.which("journalctl") is None:
+        return None
+    try:
+        proc = subprocess.run(["journalctl", *args], capture_output=True, text=True, timeout=25)
+        return proc.stdout
+    except (subprocess.SubprocessError, OSError):
+        return None
+
+
+def check_journal() -> list[Finding]:
+    out = _journalctl(["-k", "--no-pager", "-o", "cat", "--since", "-7 days"])
+    if out is None:
+        return [Finding(
+            INFO, "Logs", "Couldn't read the kernel journal",
+            "journalctl is unavailable or not readable.",
+            "Ensure systemd/journald is present and your user is in the 'systemd-journal' or 'adm' group.",
+        )]
+    findings = scan_journal_text(out)
+    if not findings:
+        findings.append(Finding(
+            OK, "Logs", "No notable kernel errors (last 7 days)",
+            "No Xid, panic, OOM, MCE, PCIe AER, or thermal events found.",
+        ))
+    return findings
+
+
+def check_journal_persistence() -> list[Finding]:
+    if Path("/var/log/journal").is_dir():
+        return []
+    return [Finding(
+        WARNING, "Logs", "journald isn't persistent across reboots",
+        "Crash-boot kernel logs are discarded on reboot, so a hard freeze's evidence can vanish.",
+        "Enable persistent logging: `sudo mkdir -p /var/log/journal && sudo systemctl restart systemd-journald`",
+    )]
+
+
+def check_nvidia_driver() -> list[Finding]:
+    if shutil.which("nvidia-smi") is None:
+        return []
+    try:
+        proc = subprocess.run(["nvidia-smi"], capture_output=True, text=True, timeout=10)
+    except (subprocess.SubprocessError, OSError):
+        return []
+    if "Driver/library version mismatch" in (proc.stdout + proc.stderr):
+        return [Finding(
+            CRITICAL, "Driver", "NVIDIA driver/library version mismatch",
+            "The loaded kernel module and the userspace NVIDIA libraries differ — GPU monitoring will fail until resolved.",
+            "Reboot to load the matching module (or finish the interrupted driver update).",
+        )]
+    return []
+
+
+def _smart_devices() -> list[str]:
+    try:
+        proc = subprocess.run(["smartctl", "--scan"], capture_output=True, text=True, timeout=10)
+    except (subprocess.SubprocessError, OSError):
+        return []
+    devices = []
+    for line in proc.stdout.splitlines():
+        line = line.strip()
+        if line.startswith("/dev/"):
+            devices.append(line.split()[0])
+    return devices
+
+
+def check_smart() -> list[Finding]:
+    if shutil.which("smartctl") is None:
+        return [Finding(
+            INFO, "Storage", "SMART not checked (smartmontools missing)",
+            "Disk self-health couldn't be read.",
+            "Install it for disk health checks: `sudo apt install smartmontools`",
+        )]
+    devices = _smart_devices()
+    if not devices:
+        return [Finding(
+            INFO, "Storage", "SMART: couldn't enumerate drives",
+            "Reading SMART usually needs root.",
+            "Run: `sudo rigdoctor report`",
+        )]
+    findings: list[Finding] = []
+    for dev in devices:
+        try:
+            proc = subprocess.run(["smartctl", "-H", dev], capture_output=True, text=True, timeout=15)
+        except (subprocess.SubprocessError, OSError):
+            continue
+        combined = proc.stdout + proc.stderr
+        if "Permission denied" in combined or "requires root" in combined.lower():
+            findings.append(Finding(INFO, "Storage", f"SMART for {dev} needs root", "", "Run: `sudo rigdoctor report`"))
+        elif "PASSED" in combined:
+            findings.append(Finding(OK, "Storage", f"SMART OK: {dev}", "Overall-health self-assessment passed."))
+        elif "FAILED" in combined or "FAILING_NOW" in combined:
+            findings.append(Finding(CRITICAL, "Storage", f"SMART FAILED: {dev}", "The drive reports failing health.", "Back up now and replace the drive."))
+    return findings
+
+
+def check_live_temps() -> list[Finding]:
+    from .sampler import Sampler
+    from .sources import available_sources
+
+    sample = Sampler(available_sources()).sample()
+    hot = [
+        (r.source, r.label or r.metric, r.value)
+        for r in sample.readings
+        if r.unit == "°C" and r.value is not None and r.value >= 90
+    ]
+    if not hot:
+        return []
+    worst = max(hot, key=lambda x: x[2])
+    detail = "; ".join(f"{s} {label} {v:.0f}°C" for s, label, v in hot)
+    return [Finding(
+        WARNING, "Thermal", f"High temperature right now ({worst[2]:.0f}°C)",
+        detail, "Check cooling/airflow and reduce load.",
+    )]
+
+
+def run_health_checks() -> list[Finding]:
+    """Run all checks and return findings sorted by severity (worst first)."""
+    findings: list[Finding] = []
+    findings += check_nvidia_driver()
+    findings += check_journal()
+    findings += check_journal_persistence()
+    findings += check_smart()
+    findings += check_live_temps()
+    findings.sort(key=lambda f: _ORDER.get(f.severity, 9))
+    return findings

src/rigdoctor/core/installer.py

@@ -0,0 +1,58 @@
+"""Optional-dependency installer (M9): figure out what's missing and install it.
+
+apt-only (D15). Installs run via pkexec/sudo so a normal user gets a single auth
+prompt; nothing is installed without an explicit confirmation by the caller.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import subprocess
+from collections.abc import Callable
+
+from . import sysenv
+from .catalog import COMPONENTS, Component
+
+
+def component_status(present: Callable[[str], bool] | None = None) -> list[tuple[Component, bool]]:
+    """Pair each catalog component with whether it's installed (command present)."""
+    present = present or sysenv.has_command
+    return [(c, present(c.command)) for c in COMPONENTS]
+
+
+def missing_packages(components: list[Component]) -> list[str]:
+    """De-duplicated apt package list for the given components, order preserved."""
+    packages: list[str] = []
+    for component in components:
+        for pkg in component.apt:
+            if pkg not in packages:
+                packages.append(pkg)
+    return packages
+
+
+def apt_install_command(packages: list[str]) -> list[str]:
+    """Build an `apt-get update && install` command, elevated if we're not root."""
+    inner = "apt-get update && apt-get install -y " + " ".join(shlex.quote(p) for p in packages)
+    cmd = ["/bin/sh", "-c", inner]
+    if os.geteuid() == 0:
+        return cmd
+    if shutil.which("pkexec"):
+        return ["pkexec", *cmd]
+    if shutil.which("sudo"):
+        return ["sudo", *cmd]
+    return cmd  # no privilege escalation available — will likely fail, surfaced to the caller
+
+
+def install_packages(packages: list[str]) -> tuple[int, str]:
+    """Install the given packages. Returns (exit_code, combined_output)."""
+    if not packages:
+        return (0, "Nothing to install.")
+    try:
+        proc = subprocess.run(
+            apt_install_command(packages), capture_output=True, text=True, timeout=900
+        )
+        return (proc.returncode, proc.stdout + proc.stderr)
+    except (subprocess.SubprocessError, OSError) as exc:
+        return (1, str(exc))

src/rigdoctor/core/sysenv.py

@@ -0,0 +1,49 @@
+"""Environment detection for the installer (M9)."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+
+def package_manager() -> str | None:
+    """Only apt is supported (D15); return 'apt' if present, else None."""
+    if shutil.which("apt-get") or shutil.which("apt"):
+        return "apt"
+    return None
+
+
+def has_command(cmd: str) -> bool:
+    return shutil.which(cmd) is not None
+
+
+def distro_name() -> str:
+    try:
+        data: dict[str, str] = {}
+        with open("/etc/os-release") as f:
+            for line in f:
+                key, _, value = line.partition("=")
+                data[key.strip()] = value.strip().strip('"')
+        return data.get("PRETTY_NAME") or data.get("NAME") or "Linux"
+    except OSError:
+        return "Linux"
+
+
+def gpu_vendors() -> list[str]:
+    vendors: list[str] = []
+    if shutil.which("nvidia-smi"):
+        vendors.append("NVIDIA")
+    out = ""
+    if shutil.which("lspci"):
+        try:
+            out = subprocess.run(["lspci"], capture_output=True, text=True, timeout=10).stdout
+        except (subprocess.SubprocessError, OSError):
+            out = ""
+    low = out.lower()
+    if "nvidia" in low and "NVIDIA" not in vendors:
+        vendors.append("NVIDIA")
+    if ("amd/ati" in low or "advanced micro devices" in low or "radeon" in low) and "AMD" not in vendors:
+        vendors.append("AMD")
+    if "intel" in low and any(k in low for k in ("vga", "display", "graphics")) and "Intel" not in vendors:
+        vendors.append("Intel")
+    return vendors

src/rigdoctor/core/updates.py

@@ -0,0 +1,97 @@
+"""Update check (M13): ask the Gitea releases API for the latest version.
+
+Stdlib-only (urllib). The Gitea instance requires sign-in, so updates are gated to
+account holders via a Personal Access Token (D18): set $RIGDOCTOR_TOKEN or save one
+with `rigdoctor login`. Self-update (apply) is built on top of this; this module
+handles detection and exposes a clear state for the UI.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+
+from .. import __version__
+from ..config import load_token
+
+GITEA_BASE = "https://git.jesseyvanofferen.com"
+REPO = "jessey/rigdoctor"
+LATEST_API = f"{GITEA_BASE}/api/v1/repos/{REPO}/releases/latest"
+RELEASES_PAGE = f"{GITEA_BASE}/{REPO}/releases"
+TOKEN_PAGE = f"{GITEA_BASE}/user/settings/applications"
+
+# Update states
+NO_TOKEN = "no-token"
+AUTH = "auth"
+NETWORK = "network"
+UP_TO_DATE = "up-to-date"
+AVAILABLE = "available"
+
+
+def _parse(version: str) -> tuple[int, ...]:
+    return tuple(int(p) for p in version.lstrip("vV").split(".") if p.isdigit())
+
+
+def is_newer(latest: str, current: str = __version__) -> bool:
+    try:
+        return _parse(latest) > _parse(current)
+    except (ValueError, AttributeError):
+        return False
+
+
+def fetch_latest(timeout: float = 5.0) -> tuple[str | None, str | None]:
+    """Return (tag, error). error is one of NO_TOKEN / AUTH / NETWORK, or None on success."""
+    token = load_token()
+    if not token:
+        return (None, NO_TOKEN)
+    req = urllib.request.Request(
+        LATEST_API,
+        headers={"Accept": "application/json", "Authorization": f"token {token}"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 (https)
+            data = json.load(resp)
+        return (data.get("tag_name") or None, None)
+    except urllib.error.HTTPError as exc:
+        return (None, AUTH if exc.code in (401, 403) else NETWORK)
+    except Exception:
+        return (None, NETWORK)
+
+
+def check_latest(timeout: float = 5.0) -> str | None:
+    """Convenience: latest tag or None (ignores error reason)."""
+    tag, _ = fetch_latest(timeout)
+    return tag
+
+
+def update_state(timeout: float = 5.0) -> tuple[str, str | None]:
+    """Return (state, tag). state in NO_TOKEN/AUTH/NETWORK/UP_TO_DATE/AVAILABLE."""
+    tag, error = fetch_latest(timeout)
+    if error:
+        return (error, None)
+    if tag and is_newer(tag):
+        return (AVAILABLE, tag)
+    return (UP_TO_DATE, tag)
+
+
+def apply_update(tag: str) -> tuple[int, str]:
+    """Self-update the current (user-local) install to `tag` via authenticated pip.
+
+    Installs `rigdoctor[gui] @ git+https://oauth2:<token>@…/rigdoctor.git@<tag>` into
+    the running environment. Returns (exit_code, output) with the token scrubbed.
+    """
+    token = load_token()
+    if not token:
+        return (1, "No update token configured. Run `rigdoctor login`.")
+    host = GITEA_BASE.split("://", 1)[1]
+    ref = f"rigdoctor[gui] @ git+https://oauth2:{token}@{host}/{REPO}.git@{tag}"
+    cmd = [sys.executable, "-m", "pip", "install", "--upgrade", ref]
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=1800)
+        out = (proc.stdout + proc.stderr).replace(token, "***")
+        return (proc.returncode, out)
+    except (subprocess.SubprocessError, OSError) as exc:
+        return (1, str(exc).replace(token, "***"))

src/rigdoctor/gui/health_page.py

@@ -0,0 +1,125 @@
+"""Health page (M4 in the GUI): runs the health checks and shows findings as cards."""
+
+from __future__ import annotations
+
+import threading
+import time
+
+from PySide6.QtCore import Qt, QTimer, Signal
+from PySide6.QtWidgets import (
+    QFrame,
+    QHBoxLayout,
+    QLabel,
+    QPushButton,
+    QScrollArea,
+    QVBoxLayout,
+    QWidget,
+)
+
+from .theme import ACCENT, CRIT, GOOD, MUTED, WARN
+
+_SEV = {
+    "critical": ("CRITICAL", CRIT),
+    "warning": ("WARNING", WARN),
+    "info": ("INFO", MUTED),
+    "ok": ("OK", GOOD),
+}
+
+
+def _finding_widget(finding) -> QFrame:
+    label, color = _SEV.get(finding.severity, ("?", MUTED))
+    card = QFrame()
+    card.setObjectName("Card")
+    v = QVBoxLayout(card)
+    v.setContentsMargins(16, 12, 16, 12)
+    v.setSpacing(4)
+
+    head = QLabel(f"{label}  ·  {finding.category}: {finding.title}")
+    head.setStyleSheet(f"color: {color}; font-weight: 700; background: transparent;")
+    head.setWordWrap(True)
+    v.addWidget(head)
+
+    if finding.detail:
+        detail = QLabel(finding.detail)
+        detail.setObjectName("Muted")
+        detail.setWordWrap(True)
+        v.addWidget(detail)
+    if finding.suggestion:
+        suggestion = QLabel(f"→ {finding.suggestion}")
+        suggestion.setStyleSheet(f"color: {ACCENT}; background: transparent;")
+        suggestion.setWordWrap(True)
+        v.addWidget(suggestion)
+    return card
+
+
+class HealthPage(QWidget):
+    _result = Signal(object)  # list[Finding]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.setObjectName("Page")
+        self._result.connect(self._render_findings)
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(20, 18, 20, 18)
+        root.setSpacing(16)
+
+        header = QHBoxLayout()
+        title = QLabel("Health")
+        title.setObjectName("PageTitle")
+        header.addWidget(title)
+        header.addStretch(1)
+        self._status = QLabel("")
+        self._status.setObjectName("Muted")
+        header.addWidget(self._status)
+        self._run_btn = QPushButton("Run health report")
+        self._run_btn.setObjectName("PrimaryButton")
+        self._run_btn.clicked.connect(self._run)
+        header.addWidget(self._run_btn)
+        root.addLayout(header)
+
+        scroll = QScrollArea()
+        scroll.setWidgetResizable(True)
+        scroll.setFrameShape(QFrame.Shape.NoFrame)
+        scroll.setStyleSheet("background: transparent;")
+        self._container = QWidget()
+        self._list = QVBoxLayout(self._container)
+        self._list.setContentsMargins(0, 0, 0, 0)
+        self._list.setSpacing(10)
+        self._list.setAlignment(Qt.AlignmentFlag.AlignTop)
+        scroll.setWidget(self._container)
+        root.addWidget(scroll, 1)
+
+        QTimer.singleShot(300, self._run)  # auto-run shortly after the window opens
+
+    def _run(self) -> None:
+        self._run_btn.setEnabled(False)
+        self._status.setText("Scanning logs, SMART, and driver…")
+        threading.Thread(target=self._work, daemon=True).start()
+
+    def _work(self) -> None:
+        from ..core.health import run_health_checks
+
+        try:
+            findings = run_health_checks()
+        except Exception:
+            findings = []
+        self._result.emit(findings)
+
+    def _render_findings(self, findings) -> None:
+        while self._list.count():
+            item = self._list.takeAt(0)
+            w = item.widget()
+            if w is not None:
+                w.deleteLater()
+
+        crit = sum(1 for f in findings if f.severity == "critical")
+        warn = sum(1 for f in findings if f.severity == "warning")
+        self._status.setText(
+            f"{crit} critical · {warn} warning · {len(findings)} checks  ·  "
+            f"{time.strftime('%H:%M:%S')}"
+        )
+        for finding in findings:
+            self._list.addWidget(_finding_widget(finding))
+        self._list.addStretch(1)
+        self._run_btn.setEnabled(True)

src/rigdoctor/gui/main_window.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
-from PySide6.QtCore import Qt
+import threading
+
+from PySide6.QtCore import Qt, Signal
 from PySide6.QtWidgets import (
     QButtonGroup,
     QFrame,
@@ -15,19 +17,25 @@ from PySide6.QtWidgets import (
     QWidget,
 )
 
+from .. import __version__
+from ..core import updates
 from .dashboard import Dashboard
+from .health_page import HealthPage
 from .recorder_page import RecorderPage
-from .theme import ACCENT, MUTED
+from .setup_page import SetupPage
+from .theme import ACCENT, GOOD, MUTED
 from .worker import SamplerWorker
 
-_NAV_ITEMS = ["Dashboard", "Logs", "Health", "Inventory"]
+_NAV_ITEMS = ["Dashboard", "Logs", "Health", "Setup", "Inventory"]
 _PLACEHOLDERS = {
-    "Health": "The health report (M4) — log scan + plain-language findings — lands here.",
     "Inventory": "System inventory (M5) — CPU/GPU/board/RAM/drivers — lands here.",
 }
 
 
 class MainWindow(QMainWindow):
+    _update_checked = Signal(object)  # (state, tag)
+    _update_applied = Signal(int)     # pip exit code
+
     def __init__(self, interval: float = 1.0) -> None:
         super().__init__()
         self.setWindowTitle("RigDoctor")
@@ -47,10 +55,13 @@ class MainWindow(QMainWindow):
         self._stack = QStackedWidget()
         self.dashboard = Dashboard()
         self.recorder_page = RecorderPage()
+        self.health_page = HealthPage()
+        self.setup_page = SetupPage()
         self._stack.addWidget(self.dashboard)            # 0 Dashboard
         self._stack.addWidget(self.recorder_page)        # 1 Logs
-        self._stack.addWidget(self._placeholder_page("Health", _PLACEHOLDERS["Health"]))      # 2
+        self._stack.addWidget(self.health_page)          # 2 Health
-        self._stack.addWidget(self._placeholder_page("Inventory", _PLACEHOLDERS["Inventory"]))  # 3
+        self._stack.addWidget(self.setup_page)           # 3 Setup
+        self._stack.addWidget(self._placeholder_page("Inventory", _PLACEHOLDERS["Inventory"]))  # 4
         content_layout.addWidget(self._stack)
 
         layout.addWidget(self._build_sidebar())
@@ -60,6 +71,12 @@ class MainWindow(QMainWindow):
         self._worker.sampled.connect(self.dashboard.update_sample)
         self._worker.start()
 
+        # Background update check (M13); result lands in the sidebar.
+        self._latest_tag = None
+        self._update_checked.connect(self._show_update_state)
+        self._update_applied.connect(self._on_update_applied)
+        threading.Thread(target=self._check_updates, daemon=True).start()
+
     def _build_sidebar(self) -> QFrame:
         bar = QFrame()
         bar.setObjectName("Sidebar")
@@ -91,8 +108,58 @@ class MainWindow(QMainWindow):
         v.addStretch(1)
         live = QLabel(f'<span style="color:{ACCENT};">●</span> <span style="color:{MUTED};">Live</span>')
         v.addWidget(live)
+        version = QLabel(f"v{__version__}")
+        version.setObjectName("Muted")
+        v.addWidget(version)
+
+        # Update state (filled in by the background check).
+        self._update_label = QLabel("checking for updates…")
+        self._update_label.setObjectName("Muted")
+        v.addWidget(self._update_label)
+        self._update_btn = QPushButton()
+        self._update_btn.setObjectName("PrimaryButton")
+        self._update_btn.setCursor(Qt.CursorShape.PointingHandCursor)
+        self._update_btn.clicked.connect(self._apply_update)
+        self._update_btn.setVisible(False)
+        v.addWidget(self._update_btn)
         return bar
 
+    def _apply_update(self) -> None:
+        if not self._latest_tag:
+            return
+        self._update_btn.setEnabled(False)
+        self._update_label.setText("updating…")
+        tag = self._latest_tag
+        threading.Thread(target=lambda: self._update_applied.emit(updates.apply_update(tag)[0]), daemon=True).start()
+
+    def _on_update_applied(self, rc: int) -> None:
+        if rc == 0:
+            self._update_label.setText("updated — restart RigDoctor")
+            self._update_btn.setVisible(False)
+        else:
+            self._update_label.setText("update failed")
+            self._update_btn.setEnabled(True)
+
+    def _check_updates(self) -> None:
+        self._update_checked.emit(updates.update_state())
+
+    def _show_update_state(self, result) -> None:
+        state, tag = result
+        self._latest_tag = tag
+        self._update_btn.setVisible(False)
+        if state == updates.NO_TOKEN:
+            self._update_label.setText("connect to update server")
+        elif state == updates.AUTH:
+            self._update_label.setText("update access denied")
+        elif state == updates.NETWORK:
+            self._update_label.setText("update check unavailable")
+        elif state == updates.AVAILABLE:
+            self._update_label.setText(f'<span style="color:{GOOD};">{tag} available</span>')
+            self._update_btn.setText(f"Update to {tag}")
+            self._update_btn.setVisible(True)
+        else:  # UP_TO_DATE
+            self._update_label.setText("up-to-date")
+
     def _placeholder_page(self, title: str, description: str) -> QWidget:
         page = QWidget()
         page.setObjectName("Page")

src/rigdoctor/gui/setup_page.py

@@ -0,0 +1,200 @@
+"""Setup page (M9 in the GUI): show environment + optional components, install missing."""
+
+from __future__ import annotations
+
+import threading
+
+from PySide6.QtCore import Qt, QUrl, Signal
+from PySide6.QtGui import QDesktopServices
+from PySide6.QtWidgets import (
+    QFrame,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QPushButton,
+    QSizePolicy,
+    QTextEdit,
+    QVBoxLayout,
+    QWidget,
+)
+
+from .. import config
+from ..core import installer, sysenv, updates
+from .theme import GOOD, MUTED, WARN
+
+
+def _panel(title: str) -> tuple[QFrame, QVBoxLayout]:
+    frame = QFrame()
+    frame.setObjectName("Card")
+    frame.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Maximum)
+    layout = QVBoxLayout(frame)
+    layout.setContentsMargins(16, 14, 16, 14)
+    layout.setSpacing(8)
+    label = QLabel(title)
+    label.setStyleSheet("font-weight: 700; background: transparent;")
+    layout.addWidget(label)
+    return frame, layout
+
+
+_BACKEND_DESC = {
+    "env": "token from $RIGDOCTOR_TOKEN",
+    "keyring": "token stored in the OS keyring (encrypted)",
+    "file": "token stored in a 0600 file — install libsecret-tools to encrypt it",
+    "none": "no token saved",
+}
+
+
+class SetupPage(QWidget):
+    _installed = Signal(int, str)
+    _upd_state = Signal(object)
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.setObjectName("Page")
+        self._installed.connect(self._on_installed)
+        self._upd_state.connect(self._on_upd_state)
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(20, 18, 20, 18)
+        root.setSpacing(16)
+
+        title = QLabel("Setup")
+        title.setObjectName("PageTitle")
+        root.addWidget(title)
+
+        env_card, env_layout = _panel("Environment")
+        self._env = QLabel("")
+        self._env.setObjectName("Muted")
+        env_layout.addWidget(self._env)
+        root.addWidget(env_card)
+
+        comp_card, comp_layout = _panel("Optional components")
+        self._components = QVBoxLayout()
+        self._components.setSpacing(6)
+        comp_layout.addLayout(self._components)
+        controls = QHBoxLayout()
+        self._install_btn = QPushButton("Install missing")
+        self._install_btn.setObjectName("PrimaryButton")
+        self._install_btn.clicked.connect(self._install)
+        self._refresh_btn = QPushButton("Re-check")
+        self._refresh_btn.clicked.connect(self._refresh)
+        controls.addWidget(self._install_btn)
+        controls.addWidget(self._refresh_btn)
+        controls.addStretch(1)
+        comp_layout.addLayout(controls)
+        root.addWidget(comp_card)
+
+        # Update access (M13): token gating updates to Gitea account holders.
+        upd_card, upd_layout = _panel("Update access")
+        self._upd_status = QLabel("")
+        self._upd_status.setObjectName("Muted")
+        self._upd_status.setWordWrap(True)
+        upd_layout.addWidget(self._upd_status)
+        token_row = QHBoxLayout()
+        self._token_input = QLineEdit()
+        self._token_input.setEchoMode(QLineEdit.EchoMode.Password)
+        self._token_input.setPlaceholderText("Paste a Gitea token (scope: read:repository)")
+        save_btn = QPushButton("Save token")
+        save_btn.setObjectName("PrimaryButton")
+        save_btn.clicked.connect(self._save_token)
+        get_btn = QPushButton("Get a token")
+        get_btn.clicked.connect(lambda: QDesktopServices.openUrl(QUrl(updates.TOKEN_PAGE)))
+        token_row.addWidget(self._token_input, 1)
+        token_row.addWidget(save_btn)
+        token_row.addWidget(get_btn)
+        upd_layout.addLayout(token_row)
+        root.addWidget(upd_card)
+
+        self._output = QTextEdit()
+        self._output.setObjectName("Report")
+        self._output.setReadOnly(True)
+        self._output.setMinimumHeight(180)
+        self._output.setVisible(False)
+        root.addWidget(self._output)
+        root.addStretch(1)
+
+        self._refresh()
+        self._refresh_update_status()
+
+    def _refresh(self) -> None:
+        self._env.setText(
+            f"Distro: {sysenv.distro_name()}    "
+            f"Package manager: {sysenv.package_manager() or 'none (apt required)'}    "
+            f"GPU: {', '.join(sysenv.gpu_vendors()) or 'unknown'}"
+        )
+        while self._components.count():
+            item = self._components.takeAt(0)
+            w = item.widget()
+            if w is not None:
+                w.deleteLater()
+
+        status = installer.component_status()
+        for component, present in status:
+            mark = "✓" if present else "✗"
+            color = GOOD if present else MUTED
+            row = QLabel(f"<span style='color:{color}'>[{mark}]</span>  "
+                         f"<b>{component.name}</b> — {component.enables}")
+            row.setTextFormat(Qt.TextFormat.RichText)
+            row.setWordWrap(True)
+            self._components.addWidget(row)
+
+        self._missing = [c for c, present in status if not present]
+        self._install_btn.setEnabled(bool(self._missing) and sysenv.package_manager() == "apt")
+        if not self._missing:
+            self._install_btn.setText("All installed ✔")
+
+    def _install(self) -> None:
+        packages = installer.missing_packages(self._missing)
+        if not packages:
+            return
+        self._install_btn.setEnabled(False)
+        self._install_btn.setText("Installing… (may prompt for password)")
+        self._output.setVisible(True)
+        self._output.setPlainText(f"Installing: {' '.join(packages)}\n")
+        threading.Thread(target=self._work, args=(packages,), daemon=True).start()
+
+    def _work(self, packages: list[str]) -> None:
+        rc, out = installer.install_packages(packages)
+        self._installed.emit(rc, out)
+
+    def _on_installed(self, rc: int, out: str) -> None:
+        self._output.setPlainText(out[-4000:])
+        self._install_btn.setText("Install missing")
+        self._refresh()
+        # If libsecret-tools was just installed, move a file token into the keyring.
+        if config.token_backend() == "file" and config.keyring_available():
+            token = config.load_token()
+            if token:
+                config.save_token(token)
+        self._refresh_update_status()
+
+    # --- update access (token) ------------------------------------------------
+    def _save_token(self) -> None:
+        token = self._token_input.text().strip()
+        if not token:
+            return
+        config.save_token(token)
+        self._token_input.clear()
+        self._refresh_update_status()
+
+    def _refresh_update_status(self) -> None:
+        self._upd_status.setText(f"{_BACKEND_DESC[config.token_backend()]} · checking…")
+        threading.Thread(target=self._check_update, daemon=True).start()
+
+    def _check_update(self) -> None:
+        self._upd_state.emit((config.token_backend(), updates.update_state()))
+
+    def _on_upd_state(self, result) -> None:
+        backend, (state, tag) = result
+        msg = {
+            updates.NO_TOKEN: "paste a token below to enable updates",
+            updates.AUTH: "token rejected — check its scope/permissions",
+            updates.NETWORK: "couldn't reach the update server",
+            updates.UP_TO_DATE: f"up to date ({tag})" if tag else "up to date",
+            updates.AVAILABLE: f"update available: {tag}",
+        }[state]
+        color = GOOD if state == updates.AVAILABLE else (WARN if state == updates.AUTH else MUTED)
+        self._upd_status.setText(
+            f"<span style='color:{MUTED}'>{_BACKEND_DESC[backend]}</span> · "
+            f"<span style='color:{color}'>{msg}</span>"
+        )

src/rigdoctor/render.py

@@ -99,6 +99,25 @@ def _aggregate_peaks(maxima: dict) -> list[tuple[str, str, float, str, float, st
     return rows
 
 
+_SEV_LABEL = {"critical": "CRITICAL", "warning": "WARNING", "info": "INFO", "ok": "OK"}
+
+
+def render_health(findings: list) -> str:
+    if not findings:
+        return "Health report: no findings."
+    crit = sum(1 for f in findings if f.severity == "critical")
+    warn = sum(1 for f in findings if f.severity == "warning")
+    lines = ["Health report", "", f"  {crit} critical · {warn} warning · {len(findings)} checks", ""]
+    for f in findings:
+        lines.append(f"[{_SEV_LABEL.get(f.severity, '?')}] {f.category}: {f.title}")
+        if f.detail:
+            lines.append(f"    {f.detail}")
+        if f.suggestion:
+            lines.append(f"    → {f.suggestion}")
+        lines.append("")
+    return "\n".join(lines).rstrip()
+
+
 def render_summary(summary: Summary, log_path=None) -> str:
     if summary.samples == 0 and not summary.events:
         where = f" ({log_path})" if log_path else ""

tests/test_health.py

@@ -0,0 +1,46 @@
+"""Tests for the M4 health report's log scanner (synthetic input)."""
+
+import unittest
+
+from rigdoctor.core.health import CRITICAL, WARNING, run_health_checks, scan_journal_text
+
+
+class HealthScanTests(unittest.TestCase):
+    def test_xid_79_is_critical(self):
+        text = "NVRM: Xid (PCI:0000:01:00): 79, pid=1234, GPU has fallen off the bus."
+        findings = scan_journal_text(text)
+        gpu = [f for f in findings if f.category == "GPU"]
+        self.assertEqual(len(gpu), 1)
+        self.assertIn("79", gpu[0].title)
+        self.assertEqual(gpu[0].severity, CRITICAL)
+
+    def test_xid_count_aggregates(self):
+        text = "\n".join(["NVRM: Xid (PCI:0000:01:00): 79, foo"] * 3)
+        gpu = [f for f in scan_journal_text(text) if f.category == "GPU"][0]
+        self.assertIn("×3", gpu.title)
+
+    def test_oom_and_panic_detected(self):
+        text = "Out of memory: Killed process 999 (game)\nKernel panic - not syncing: x"
+        cats = {f.category for f in scan_journal_text(text)}
+        self.assertIn("Memory", cats)
+        self.assertIn("Kernel", cats)
+
+    def test_mce_critical(self):
+        findings = scan_journal_text("mce: [Hardware Error]: Machine check events logged")
+        self.assertTrue(any(f.severity == CRITICAL and f.category == "Hardware" for f in findings))
+
+    def test_clean_text_yields_no_findings(self):
+        self.assertEqual(scan_journal_text("usb 1-1: new high-speed USB device\nbluetooth: ok"), [])
+
+    def test_run_health_checks_returns_findings(self):
+        # Runs against the real system; just assert it returns a sorted list of Findings.
+        findings = run_health_checks()
+        self.assertIsInstance(findings, list)
+        severities = [f.severity for f in findings]
+        order = {"critical": 0, "warning": 1, "info": 2, "ok": 3}
+        ranks = [order.get(s, 9) for s in severities]
+        self.assertEqual(ranks, sorted(ranks))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_installer.py

@@ -0,0 +1,46 @@
+"""Tests for the M9 installer logic and the M13 version comparison."""
+
+import unittest
+
+from rigdoctor.core import installer
+from rigdoctor.core.catalog import Component
+from rigdoctor.core.updates import is_newer
+
+
+class InstallerTests(unittest.TestCase):
+    def test_component_status_uses_presence(self):
+        status = installer.component_status(present=lambda cmd: cmd == "smartctl")
+        by_id = {c.id: ok for c, ok in status}
+        self.assertTrue(by_id["smartmontools"])
+        self.assertFalse(by_id["dmidecode"])
+
+    def test_missing_packages_dedup_preserves_order(self):
+        comps = [
+            Component("a", "A", "B", "x", ("p1", "p2"), "c1"),
+            Component("b", "B", "B", "y", ("p2", "p3"), "c2"),
+        ]
+        self.assertEqual(installer.missing_packages(comps), ["p1", "p2", "p3"])
+
+    def test_apt_command_includes_packages(self):
+        joined = " ".join(installer.apt_install_command(["smartmontools", "dmidecode"]))
+        self.assertIn("smartmontools", joined)
+        self.assertIn("dmidecode", joined)
+        self.assertIn("apt-get install", joined)
+
+    def test_install_nothing_is_noop(self):
+        rc, _ = installer.install_packages([])
+        self.assertEqual(rc, 0)
+
+
+class UpdateTests(unittest.TestCase):
+    def test_is_newer(self):
+        self.assertTrue(is_newer("v0.0.5", "0.0.4"))
+        self.assertFalse(is_newer("v0.0.4", "0.0.4"))
+        self.assertFalse(is_newer("v0.0.3", "0.0.4"))
+
+    def test_is_newer_handles_garbage(self):
+        self.assertFalse(is_newer("not-a-version", "0.0.4"))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_token.py

@@ -0,0 +1,36 @@
+"""Tests for update-token storage (file fallback + env override), keyring mocked out."""
+
+import os
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from rigdoctor import config
+
+
+class TokenStorageTests(unittest.TestCase):
+    def test_file_fallback_roundtrip(self):
+        with tempfile.TemporaryDirectory() as d:
+            token_file = Path(d) / "token"
+            with mock.patch.object(config, "_secret_tool", return_value=None), \
+                 mock.patch.object(config, "TOKEN_FILE", token_file), \
+                 mock.patch.dict(os.environ, {}, clear=True):
+                self.assertIsNone(config.load_token())
+                config.save_token("abc123")
+                self.assertEqual(config.load_token(), "abc123")
+                self.assertEqual(config.token_backend(), "file")
+                self.assertEqual(token_file.stat().st_mode & 0o777, 0o600)
+                config.clear_token()
+                self.assertIsNone(config.load_token())
+                self.assertEqual(config.token_backend(), "none")
+
+    def test_env_override_wins(self):
+        with mock.patch.object(config, "_secret_tool", return_value=None), \
+             mock.patch.dict(os.environ, {"RIGDOCTOR_TOKEN": "envtok"}, clear=True):
+            self.assertEqual(config.load_token(), "envtok")
+            self.assertEqual(config.token_backend(), "env")
+
+
+if __name__ == "__main__":
+    unittest.main()