Merge pull request 'feat(gui): dashboard history graphs for headline metrics — 0.14.0' (#9 ) from feat/m6-steam-detection into main

Reviewed-on: #9
feat(gui): dashboard history graphs for headline metrics — 0.14.0
2026-05-22 06:51:06 +00:00 · 2026-05-22 08:45:20 +02:00 · 2026-05-22 06:43:57 +00:00 · 2026-05-22 08:40:50 +02:00 · 2026-05-22 06:32:30 +00:00 · 2026-05-22 08:32:04 +02:00
64 changed files with 6279 additions and 99 deletions
@@ -27,12 +27,39 @@ jobs:
          python -m pip install --upgrade build
          python -m build

+      - name: Build self-extracting installer (.run)
+        run: python packaging/make_run.py
+
      - name: Read version
        id: ver
        run: |
          V=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
          echo "version=$V" >> "$GITHUB_OUTPUT"

+      - name: Build release notes
+        run: |
+          python - <<'PY'
+          import json
+          version = "${{ steps.ver.outputs.version }}"
+          tag = f"v{version}"
+          out, capturing = [], False
+          try:
+              for line in open("CHANGELOG.md", encoding="utf-8").read().splitlines():
+                  if line.startswith("## "):
+                      if capturing:
+                          break
+                      capturing = line.startswith(f"## [{version}]")
+                      continue
+                  if capturing:
+                      out.append(line)
+          except OSError:
+              pass
+          body = "\n".join(out).strip() or f"Release {tag}."
+          payload = {"tag_name": tag, "target_commitish": "${{ github.sha }}", "name": tag, "body": body}
+          open("/tmp/release.json", "w", encoding="utf-8").write(json.dumps(payload))
+          print(f"release notes: {len(body)} chars")
+          PY
+
      - name: Publish Gitea release
        env:
          TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -52,7 +79,7 @@ jobs:
          rid=$(curl -sS -X POST \
            -H "Authorization: token ${TOKEN}" \
            -H "Content-Type: application/json" \
-            -d "{\"tag_name\":\"${TAG}\",\"target_commitish\":\"${{ github.sha }}\",\"name\":\"${TAG}\",\"body\":\"Automated release for ${TAG}. See CHANGELOG.md.\"}" \
+            -d @/tmp/release.json \
            "${API}/releases" | python -c "import sys, json; print(json.load(sys.stdin)['id'])")

          for f in dist/*; do
@@ -5,6 +5,288 @@ 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.14.0] - 2026-05-22
+### Changed
+- **Dashboard headline tiles are now history trend graphs** instead of single-value gauges —
+  GPU temp, GPU load, CPU temp, and memory each plot their recent history (with the current
+  value, window min/max, and a dashed warning-threshold line), so you can see changes over time
+  rather than only the instantaneous reading. New `HistoryGraph` widget (QPainter, no new deps).
+
+## [0.13.0] - 2026-05-22
+### Added
+- **Run Diagnostic now explains itself and can launch the game.** Clicking Run Diagnostic shows
+  what to do — *play the game, reproduce the crash, then Finish & analyze* (and that data
+  survives a hard freeze + reboot) — and offers **Launch game & start** (asks Steam to run it by
+  appid) or **Start without launching**. The recording banner now spells out the next step
+  instead of just showing a sample count.
+### Fixed
+- Button labels containing "&" (e.g. "Finish & analyze") rendered as "Finish _analyze" because
+  Qt treated the "&" as a keyboard mnemonic — now escaped so the ampersand shows literally.
+
+## [0.12.0] - 2026-05-22
+### Added
+- **Guided diagnostic in the GUI.** Each game on the **Games** page now has a **Run Diagnostic**
+  button → a focused, game-tagged capture starts and a recording banner appears (live sample
+  count, GPU-lost indicator) with **Finish & analyze** / **Discard**. Finishing opens a results
+  dialog: the window-scoped capture summary (peak temps/power, events, last samples) plus the
+  health findings as cards. The banner persists/restores if you navigate away and back while a
+  capture is running. Shares `core/diagnostic.py` with the CLI (one flow, three front-ends).
+
+## [0.11.0] - 2026-05-22
+### Added
+- **Guided diagnostic session (CLI) — the seed use case, end to end.** `rigdoctor diagnose
+  start --game "<name>"` runs a **focused crash-capture tagged with that game** (its own
+  diagnostic log, so the report is scoped to just that session), `diagnose status` shows
+  progress, and `diagnose finish` stops it and prints a combined report: the **capture
+  summary** (peak temps/power, GPU-lost events, last samples — M3) plus the **health findings**
+  (Xid/SMART/driver/etc. — M4). The game can be given by `--game` or `--appid` (resolved from
+  the Steam scan), and is recorded as a log event so it survives a crash + reboot.
+- Shared orchestration lives in `core/diagnostic.py` (one callable for CLI/GUI/tray, per
+  ARCHITECTURE §7.1); the recorder/`record run` gained an optional `--game` tag.
+
+## [0.10.2] - 2026-05-22
+### Changed
+- When an Environment **Apply**/**Install** fails, the status now shows the **real reason**
+  (cancelled at the password prompt vs. the system rejecting the change, e.g. a BIOS/kernel-
+  locked PCIe ASPM policy) instead of a vague "cancelled, or needs privileges".
+
+## [0.10.1] - 2026-05-22
+### Fixed
+- **Environment-page contrast.** The combo-box **drop-down list** was rendering light-on-light
+  (the popup view is a separate widget the theme didn't cover) — now dark with readable text.
+- The **Install / Apply** buttons on findings were hard to read (the accent fill didn't paint
+  reliably inside the finding cards, leaving dim dark-on-dark text). They're now an outlined
+  style — bright accent text on the dark card, filling accent on hover — readable regardless,
+  and given a minimum height so the row can't crush them.
+
+## [0.10.0] - 2026-05-22
+### Added
+- **Actionable Environment page (M6) — install & apply, not just advice.** Findings that
+  recommend a tool or a setting are now one-click:
+  - **Install buttons** for GameMode, MangoHud, and cpupower (added to the M9 component catalog,
+    so they also appear on the **Setup** page with the existing installer).
+  - **Apply controls** for runtime-reversible tunables — a dropdown of the live options + Apply,
+    via a single pkexec prompt, no reboot: **CPU governor**, **NVIDIA persistence mode**,
+    **PCIe ASPM policy**, **vm.swappiness**, **Transparent HugePages** (`core/fixes.py`). The
+    chosen value is validated against the live options before anything runs.
+  - This is the consent-gated apply milestone D9 anticipated, scoped to safe settings (**D22**).
+    GRUB-based fixes and CPU mitigations stay suggestion-only; `rigdoctor gameenv` still prints
+    the exact commands for headless use.
+### Changed
+- The `Finding` model gained optional `action` (installable component) and `fix` (applyable
+  tunable) fields; the shared `finding_card` widget renders the matching control.
+
+## [0.9.0] - 2026-05-22
+### Added
+- **Gaming environment checks (M6) — the evaluate-and-suggest engine.** A new read-only report
+  (D9) that flags system settings which hurt gaming stability/performance and gives the exact fix
+  command. Checks: **PCIe ASPM**, **NVIDIA persistence mode**, **CPU governor** (the three that
+  map to the seed-case GPU bus-drop / Xid 79), GameMode, MangoHud, `vm.swappiness`, shader disk
+  cache, Transparent HugePages, CPU mitigations, and installed Proton versions.
+  - **CLI:** `rigdoctor gameenv` (text or `--json`).
+  - **GUI:** a new **Environment** page (findings cards, auto-runs on open), reusing the M4
+    health-report card style via a shared `finding_card` widget.
+### Fixed
+- **Notification icon** now uses the RigDoctor icon (matching the app/dock) instead of a generic
+  stock icon — resolved from the installed icon theme, the bundled asset, then a stock fallback.
+
+## [0.8.0] - 2026-05-22
+### Added
+- **Gaming environment checks (M6) — Steam game detection.** RigDoctor now finds your Steam
+  libraries (across multiple drives, via `libraryfolders.vdf`) and the games installed in each
+  (parsing `appmanifest_*.acf` — stdlib only, no Steam tooling needed). Runtimes, Proton builds,
+  and redistributables are filtered out.
+  - **Opt-in libraries:** detected libraries are listed with a per-library game count; you check
+    the ones to scan. Nothing is scanned until you pick a library.
+  - **Background scan on every launch:** the GUI rescans the selected libraries in the background
+    when it opens and flags games installed since the last scan with a **NEW** badge plus a count
+    on the **Games** sidebar item (cleared when you view the page). Results are cached
+    (`~/.local/state/rigdoctor/games.json`) so the list shows instantly.
+  - **CLI:** `rigdoctor games` lists detected games; `rigdoctor games libraries
+    [--enable PATH | --disable PATH | --all]` lists/selects libraries (headless-complete, D17).
+- Config now supports list values (TOML arrays); `steam_libraries` records the selected libraries.
+
+## [0.7.3] - 2026-05-21
+### Fixed
+- Shared terminal now has **scrollback** — large output (e.g. `ls -la`) can be scrolled up to
+  read; it keeps a history buffer and only auto-scrolls to the bottom when you're already there.
+
+## [0.7.2] - 2026-05-21
+### Changed
+- Removed the GUI **Inventory** tab — use the CLI `rigdoctor inventory` instead. (Inventory is
+  still collected for the relay guest view, so a remote helper still sees the host's hardware.)
+### Fixed
+- Shared terminal caret now sits at the real cursor position (row **and** column) instead of
+  the start of the line.
+
+## [0.7.1] - 2026-05-21
+### Fixed
+- Shared terminal: a guest who joined **after** the host enabled the terminal stayed read-only.
+  The host now re-sends the terminal state when a guest joins, so the terminal is available.
+- Inventory page no longer jumps back to the top when it refreshes (e.g. when elevated data
+  arrives) — scroll position is preserved and unchanged data isn't re-rendered.
+- Shared terminal now follows the cursor to the bottom as output arrives (e.g. `ls -la`),
+  instead of staying scrolled up.
+
+## [0.7.0] - 2026-05-21
+### Added
+- **Shared terminal (M12, Tier 3)**: when the host enables it, the session shares a real **PTY**
+  shell — the guest gets an interactive terminal (vim, top, tab-completion, Ctrl-C) running on
+  the host as the host's user. The host **reads along** live and can type too, e.g. a `sudo`
+  password — which stays local and is never sent to the guest. Off by default, host-consented.
+  The guest also pulls the host's inventory on join.
+### Fixed
+- **Input contrast**: all form controls (text fields, spin boxes, combo boxes, terminals) now
+  use the dark theme with readable text (Fusion defaulted them to light-on-light).
+
+## [0.6.0] - 2026-05-21
+### Added
+- **Session sharing over the relay (M12)**: a **Share** tab — *Start shared session* (host)
+  hands you a short code and streams a read-only live view; *Enter share code* (guest) joins
+  someone else's session and views their sensors/health/inventory. Both connect outbound over
+  WebSocket to the relay (`relay_url`, default `wss://rigdoctor.jesseyvanofferen.com`), gated
+  by your Gitea access token — no port forwarding. Read-only.
+
+## [0.5.0] - 2026-05-21
+### Added
+- **Session sharing (M12, Tier 2)**: `rigdoctor share serve` starts a **read-only** live view
+  (sensors auto-refresh + health report + inventory) over a local HTTP server, gated by a
+  random share token. Bind to localhost for local testing, or to all interfaces behind a
+  user-chosen tunnel (Tailscale/cloudflared/SSH) for remote help. No actions, no terminal.
+  (Tier 1 export and Tier 3 gated terminal still to come — D16.)
+
+## [0.4.1] - 2026-05-21
+### Fixed
+- Checkbox contrast: a checked checkbox is now a clear accent-filled box with a checkmark
+  (was hard to tell checked from unchecked on the dark theme).
+
+## [0.4.0] - 2026-05-21
+### Added
+- **Alerts (M8)**: desktop notifications (via `notify-send`) for **overheat** (GPU/CPU past a
+  threshold), **GPU-lost** (nvidia-smi timeout), and a **new version available** (fired once
+  per version). Edge-triggered with a cooldown so it doesn't spam. Degrades gracefully if
+  `notify-send` isn't installed.
+- **Notifications page**: configure alerts (enable/disable, GPU/CPU temperature thresholds)
+  with a "Send test" button; changes apply live and persist to `config.toml`.
+- **App icon**: ships a RigDoctor icon and shows it in the dock/launcher. The GUI
+  **self-registers** the icon + `.desktop` on launch (and sets the Wayland app-id), so a
+  self-update + relaunch picks it up — no need to re-run the installer.
+
+## [0.3.2] - 2026-05-21
+### Changed
+- Replaced the per-page "Run with admin" buttons with a **single password prompt at launch**
+  (`pkexec`): the GUI collects root-only data (SMART + dmidecode board/BIOS/RAM) once and
+  caches it for the session, so Health and Inventory always show the full picture. Falls back
+  to non-root if cancelled/unavailable; disable via `elevate_on_launch = false`.
+
+## [0.3.1] - 2026-05-21
+### Fixed
+- Changelog/release notes now **render Markdown** instead of showing raw `#`/`**` markup —
+  the in-app changelog uses `QTextEdit.setMarkdown()` and the update prompt renders notes as
+  rich text (closes #1).
+
+## [0.3.0] - 2026-05-21
+### Added
+- **System inventory (M5)**: CPU, GPU (model/driver/VBIOS/VRAM/PCIe), motherboard/BIOS, RAM
+  (total + modules), storage, kernel, and display server. CLI `rigdoctor inventory`
+  (`--json` / `--markdown` / `--output`) and a GUI **Inventory** tab with Copy-as-Markdown,
+  Save, and "Run with admin" (for `dmidecode` board/BIOS/RAM details). Fills the last GUI tab.
+
+## [0.2.0] - 2026-05-21
+### Added
+- **"Check for updates" button** in the sidebar — force an immediate version check instead of
+  waiting for the 30-minute poll.
+
+## [0.1.1] - 2026-05-21
+### Fixed
+- Dialogs (the update prompt and changelog) were light-on-light and unreadable — they now use
+  the dark theme with readable text.
+
+## [0.1.0] - 2026-05-21
+_First milestone release — a complete, installable, self-updating RigDoctor: live monitoring,
+crash capture + health report, desktop GUI, user-local install/uninstall, and updates._
+### Added
+- **In-app uninstaller**: "Uninstall RigDoctor" button on the Setup page (and
+  `rigdoctor uninstall [--purge]`) — removes the venv, launchers, and desktop entry, with an
+  option to also wipe settings/token/logs. Runs detached so it can delete its own venv.
+- **In-app changelog**: a "Changelog" link in the sidebar opens the release history (tags +
+  notes) fetched from the update server.
+
+## [0.0.10] - 2026-05-21
+### Added
+- **"Restart now" button** after a successful in-app update — relaunches RigDoctor for you
+  instead of asking you to restart manually.
+- **Real release notes**: CI now sets each Gitea release's body from the matching CHANGELOG
+  section (instead of "Automated release for…"), and the updater shows **"What's new"** — a
+  notes dialog before applying (GUI) and in `rigdoctor update` (CLI).
+### Changed
+- Setup page / `rigdoctor install`: dropped internal module references (M4, M5, …) from the
+  component descriptions — end users don't need them.
+- Adopting **Conventional Commits** + **git-cliff** (`cliff.toml`, `packaging/changelog.sh`)
+  to generate CHANGELOG entries from commit history going forward (D20).
+### Fixed
+- The self-extracting **`.run` installer** is now built **without makeself** (a pure-Python
+  self-extractor, `packaging/make_run.py`), so it reliably attaches to every release — it was
+  silently skipped before because the CI runner couldn't install makeself.
+
+## [0.0.8] - 2026-05-21
+### Added
+- **Periodic update checks**: the GUI now re-checks for new releases while running (every
+  `update_check_minutes`, default 30; 0 disables), so a newly published version is detected
+  without restarting. After applying an update, re-checks stop until restart.
+- **"Run with admin" on the Health page**: runs all checks (including root-only SMART) via
+  `pkexec rigdoctor report --json`, so the full report — not just "SMART needs root" — is
+  available from the UI.
+
+## [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,
@@ -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
-> logger (M3)** work — `snapshot`/`monitor` read NVIDIA GPU, CPU, memory, and NVMe live, and
-> `record` captures a crash-safe log with a post-crash report. A desktop GUI (M10) is also
-> up. Health report (M4) is next. See `docs/ROADMAP.md`.
+> **Status:** 🟢 Phase 1 (MVP) complete. The **sensor core (M1)**, **crash-capture logger
+> (M3)**, and **health report (M4)** all work — live `snapshot`/`monitor`, crash-safe `record`
+> with a post-crash report, and `report` to scan logs/SMART/driver for likely causes. A
+> 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
-report); Health / Inventory are placeholders until M4 / M5 land.
+The **Logs** and **Health** sections are full pages (recording controls + post-crash report;
+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.

@@ -0,0 +1,42 @@
+# git-cliff configuration — generate CHANGELOG.md from Conventional Commits (D20).
+# Run via packaging/changelog.sh.
+
+[changelog]
+header = """
+# Changelog
+
+All notable changes to RigDoctor are recorded here. Format follows
+[Keep a Changelog](https://keepachangelog.com/); versioning is SemVer-style
+(`MAJOR.MINOR.PATCH`, pre-1.0). `__version__` and `pyproject.toml` must match the git
+release tag (so the auto-updater, D18, can compare versions).
+"""
+body = """
+{% for group, commits in commits | group_by(attribute="group") %}
+## {{ group | upper_first }}
+{% for commit in commits %}\
+- {{ commit.message | upper_first }}\
+{% endfor %}
+{% endfor %}
+"""
+trim = true
+
+[git]
+conventional_commits = true
+filter_unconventional = false
+commit_parsers = [
+    { message = "^feat", group = "Added" },
+    { message = "^fix", group = "Fixed" },
+    { message = "^docs", group = "Documentation" },
+    { message = "^perf", group = "Performance" },
+    { message = "^refactor", group = "Changed" },
+    { message = "^chore\\(release\\)", skip = true },
+    { message = "^chore|^build|^ci|^style|^test", group = "Internal" },
+    { message = ".*", group = "Other" },
+]
+tag_pattern = "v[0-9]*"
+sort_commits = "oldest"
+
+[bump]
+# Pre-1.0 rules (D21): feat -> minor, fix -> patch, breaking -> minor (not major).
+features_always_bump_minor = true
+breaking_always_bump_major = false
@@ -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**
@@ -178,12 +191,57 @@ RigDoctor should **check for a newer version on launch and self-update** (new mo
 PATCH for ordinary changes, MINOR for larger milestones). `__version__`
 (`rigdoctor/__init__.py`) and `pyproject.toml` are the single source of truth and **must match
 the git release tag** so the auto-updater (D18) can compare versions. Every change updates
-`CHANGELOG.md` (Keep a Changelog style). *Note:* an early placeholder `0.1.0` was corrected to
+`CHANGELOG.md` — now generated from **Conventional Commits** via git-cliff (see D20).
+*Milestone policy (pre-1.0):* **0.0.x** = early development; **0.1.0** = first complete,
+installable, self-updating release (reached 2026-05-21); **0.x.0** = each later milestone
+(AMD/Intel, unattended logger auto-start, session sharing…); **1.0.0** = broadly stable
+(multi-vendor/distro, no major caveats). PATCH (`0.x.PATCH`) for fixes/small changes. *Note:* an early placeholder `0.1.0` was corrected to
 follow the released **0.0.x** line — first release was **V0.0.1**; current is **0.0.2**.

+### D20 — Automated changelog & release notes — *DECIDED 2026-05-21*
+**Release notes are generated from our changes, surfaced in the auto-updater.**
+- *Release body:* CI sets each Gitea release's `body` from the matching `CHANGELOG.md`
+  section (was a hardcoded "Automated release for…"). The updater fetches the release `body`
+  and shows **"What's new"** — a dialog before applying (GUI) and in `rigdoctor update` (CLI).
+- *Generation:* adopt **Conventional Commits** (`feat:`/`fix:`/`docs:`/`chore:` …) and
+  **git-cliff** (`cliff.toml`, `packaging/changelog.sh`) to generate `CHANGELOG.md` from
+  commit history. Refines D19's "hand-write CHANGELOG" to "generate it from conventional
+  commits"; `__version__`/`pyproject.toml`/tag still the source of truth for the version.
+- *CI does not auto-commit the changelog* (avoids push loops) — it's regenerated by the dev
+  via the script when cutting a version; CI only reads the section for the release body.
+
+### D21 — Versioning rules & automation — *DECIDED 2026-05-21*
+The next version is **determined by the Conventional Commit types** since the last release
+(D20), so it can be auto-computed instead of guessed:
+- `fix:` / `perf:` → bump **PATCH**.
+- `feat:` → bump **MINOR** (pre-1.0: `0.MINOR.0`).
+- breaking (`feat!:` / `BREAKING CHANGE:`) → pre-1.0: bump **MINOR** (not major); post-1.0: MAJOR.
+- `docs:` / `chore:` / `refactor:` / `ci:` / `test:` / `style:` alone → **PATCH** (no feature release).
+- Milestone overrides by hand are allowed (e.g., jumping to `1.0.0`); see the milestone policy in D19.
+
+*Automation:* `git-cliff --bumped-version` computes the next version from history;
+`packaging/bump.sh` writes it into `__init__.py` + `pyproject.toml`. Rules live in
+`cliff.toml [bump]` (pre-1.0: `breaking_always_bump_major = false`).
+
+### D22 — Limited live apply of fixes (M6) — *DECIDED 2026-05-22; realizes the D9 milestone*
+D9 deferred auto-applying fixes to "a deliberate later milestone, gated behind explicit user
+consent." That milestone lands here, **scoped tightly to stay safe**:
+- **Only runtime-reversible settings** are applyable from the gaming-environment report (M6):
+  **CPU governor, NVIDIA persistence mode, PCIe ASPM policy, vm.swappiness, Transparent
+  HugePages.** Each takes effect immediately, needs **no reboot**, and reverts on reboot.
+- **How:** a dropdown of the live options + an Apply button per finding (`core/fixes.py`).
+  Applying runs a **single pkexec-elevated command** (one auth prompt); the chosen value is
+  validated against the live options first; writes target **sysfs/procfs or `nvidia-smi`** —
+  never the GRUB cmdline or a persistent config file.
+- **Still suggestion-only** (the read-only stance holds for these): GRUB-based `pcie_aspm=off`,
+  CPU **mitigations** changes (security-sensitive, need a reboot), and the shader-cache env var.
+- Everything remains **CLI-discoverable** (`rigdoctor gameenv` still prints the exact commands);
+  the apply UI is an additive convenience in the GUI, not the only path. Installing optional
+  tools (GameMode/MangoHud/cpupower) reuses the M9 installer and is likewise one-click.
+
 ## Open

-None currently — all tracked decisions (D1–D19) are resolved. New questions will be added
+None currently — all tracked decisions (D1–D22) are resolved. New questions will be added
 here as they arise. Remaining detail to flesh out during build: the tray's supporting-action
 set (D13), per-module apt package names, M12's tunnel/token specifics, and M13's
 update mechanism (APT repo vs. self-installed `.deb`).
@@ -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 | ⬜ |
+| 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 | ⬜ |
-| 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 | ⬜ |
+| 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 | 🟨 |
 | ~~M7~~ | ~~Stress / repro~~ | — | — | — | — | ❌ dropped (D7) |

 ## Notes per module
@@ -36,10 +36,28 @@ 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).
+  suggests the fix command but does not apply it (D9). *M6 implemented (Steam detection first —
+  the D12 "pick a game" foundation):* discovers Steam installs + all library folders
+  (`libraryfolders.vdf`, multi-drive) and the games in each (`appmanifest_*.acf`), filtering
+  runtimes/Proton/redistributables — stdlib only. **Libraries are opt-in** (`steam_libraries`
+  config); the GUI **Games** page lists them with per-library counts and rescans in the
+  background on every launch, badging games installed since the last scan (cached in
+  `state/games.json`). CLI: `rigdoctor games` / `games libraries [--enable|--disable|--all]`.
+  *Env-check engine implemented* (`core/gameenv.py`): a read-only findings report (reusing the
+  M4 `Finding` model) over PCIe ASPM, NVIDIA persistence mode, CPU governor (the three seed-case
+  contributors to GPU bus-drop / Xid 79), GameMode, MangoHud, swappiness, shader cache, THP, CPU
+  mitigations, and installed Proton versions — each with the suggested fix command. CLI
+  `rigdoctor gameenv`; GUI **Environment** page. Per **D22**, the GUI adds **one-click apply**
+  for the runtime-reversible tunables (governor / NVIDIA persistence / PCIe ASPM / swappiness /
+  THP — dropdown + Apply via a single pkexec prompt, `core/fixes.py`) and **one-click install**
+  of optional tools (GameMode / MangoHud / cpupower, now in the M9 catalog). GRUB/mitigations
+  stay suggestion-only. *Pending:* non-Steam launchers (Lutris/Heroic) and GPU power-profile
+  (PowerMizer) checks.
 - **M8 Alerting** — threshold/event notifications; integrates with the tray applet (M11).
 - **M10 Desktop GUI** — PySide6 graphical front-end over the core engine (dashboard, log
  browser, report viewer, logger controls). Optional; adds the Qt dependency. *Bootstrapped
@@ -52,14 +70,30 @@ 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`** (pure-Python self-extractor, `packaging/make_run.py`, 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
@@ -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,
-      suggested fixes only — D9)
+- [x] M4 health report (Xid/panic/OOM/MCE/AER/thermal scan + SMART + driver-mismatch +
+      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.
@@ -27,38 +27,54 @@ Ubuntu + NVIDIA first; `.deb` distribution (see `DECISIONS.md`).

 ## Phase 3 — Diagnostics breadth
 - [ ] M5 system inventory + exportable report
- [ ] M6 gaming environment checks (suggest-only)
+- [~] M6 gaming environment checks (suggest-only) — *Steam game/library detection done*
+      (multi-library `libraryfolders.vdf` discovery + `appmanifest` scan, opt-in libraries,
+      launch-time background rescan with new-game badge; CLI `rigdoctor games`, GUI Games page).
+      This is also the D12 "pick a game" foundation. *Env-check engine done* (`rigdoctor gameenv`
+      + GUI Environment page): PCIe ASPM, NVIDIA persistence, CPU governor, GameMode, MangoHud,
+      swappiness, shader cache, THP, mitigations, Proton versions — read-only with fix commands.
+      *Pending:* non-Steam launchers (Lutris/Heroic) + GPU power-profile (PowerMizer) checks.
 - [ ] SMART integration (smartmontools if present)

 ## Phase 4 — Desktop UI & installer
 - [ ] M10 desktop GUI (PySide6: dashboard, log browser, report viewer, logger controls)
 - [ ] M11 tray / menu-bar applet (QSystemTrayIcon: live M1 readouts + Run Diagnostic +
      supporting actions — D13)
- [ ] Guided diagnostic session (pick game → focused M3 capture → M4 scan → findings),
-      shared by tray/GUI/CLI
+- [~] Guided diagnostic session (pick game → focused M3 capture → M4 scan → findings),
+      shared by tray/GUI/CLI — *core + CLI + GUI done* (`core/diagnostic.py`, `rigdoctor
+      diagnose start/status/finish`, and a **Run Diagnostic** button per game on the GUI Games
+      page → recording banner → results dialog with the capture summary + findings). Tags a
+      focused capture with the chosen game (own diagnostic log, window-scoped report) and
+      combines the capture summary with the M4 findings. *Pending:* the tray (M11) entry point,
+      and auto start/stop via the D12 wrapper/watcher.
 - [ ] 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,
-      service enable + trigger-mode pick)
+- [~] M9 interactive installer — *done:* distro/GPU detection + optional-dependency install
+      (`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
-      user-local install from the public Gitea releases; GUI prompt + `rigdoctor update`
- [ ] (Later, separate milestone) Optional auto-apply of suggested fixes behind explicit
-      consent — currently out of scope (D9)
+- [x] M13 auto-update (D18) — launch-time version check (GUI sidebar) + no-root self-update
+      apply (`rigdoctor update` / sidebar button → authenticated pip upgrade), token-gated.
+      Restart-after-update is manual for now.
+- [~] Optional auto-apply of suggested fixes behind explicit consent (D9 milestone) — *first
+      cut shipped for M6 (D22):* one-click apply of runtime-reversible tunables (CPU governor,
+      NVIDIA persistence, PCIe ASPM, swappiness, THP) via a single pkexec prompt, no reboot.
+      GRUB-based fixes + CPU mitigations remain suggestion-only.

 ## Phase 6 — Session sharing / remote assist  (M12, D16)
 Escalating ladder, built in order:
 - [ ] Tier 1: `share export` — diagnostic bundle (inventory + recent log + report); B opens
      it in RigDoctor. One-way, safest.
- [ ] Tier 2: live read-only view (local server + user-chosen tunnel: Tailscale/cloudflared/
-      SSH; no hosted relay), token-gated, A approves, revocable.
- [ ] Tier 3: gated interactive terminal (wrap tmate/sshx; read-only default, read-write on
-      explicit consent), with session audit log.
+- [x] Tier 2: live read-only view — `rigdoctor share serve` (stdlib HTTP, token-gated:
+      sensors + health + inventory). Remote = user-chosen tunnel; GUI controls still to add.
+- [x] Tier 3: host-consented interactive terminal — a real PTY shell shared over the relay
+      (own `pty`, pyte-rendered guest), off by default; host reads along + can type (sudo).

 > **Out of scope:** stress/repro module (D7); multi-distro support and packaging beyond
 > Ubuntu/apt + `.deb` (D15) — a thin seam is kept but not built out.
@@ -43,9 +43,12 @@ RigDoctor's crash-safe logger is designed to fix exactly that.
 - **Not a stress-test / load-generator** — explicitly out of scope (D7). Users can run
  existing tools (gpu-burn, vkmark, stress-ng) alongside the logger if they want.
 - Not an overclocking utility.
- **Not (yet) an auto-fixer.** RigDoctor is **read-only**: it diagnoses and *suggests*
-  actions (with the exact command where possible) but does not apply changes itself in this
-  stage. Auto-apply is a deliberate later milestone behind explicit consent. (D9)
+- **Read-only by default, with a narrow consent-gated exception.** RigDoctor diagnoses and
+  *suggests* actions (with the exact command where possible). It does **not** apply changes
+  itself — **except** a small set of **runtime-reversible** gaming tunables (M6: CPU governor,
+  NVIDIA persistence, PCIe ASPM policy, swappiness, THP) that can be applied from the GUI via a
+  single pkexec prompt, no reboot, revert on reboot (D22, realizing the D9 milestone). Risky/
+  persistent fixes (GRUB cmdline, CPU mitigations) remain suggestion-only.

 ## 3. Target users & platforms

@@ -96,8 +99,10 @@ PCIe topology. Exportable (Markdown/JSON) to paste into forum/bug reports.
 ### M6 — Gaming environment checks
 Detects & evaluates: GPU power profile / persistence mode, CPU governor, Proton/Wine/Steam
 versions, GameMode, MangoHud, shader cache, swappiness, hugepages, CPU mitigations,
-PCIe ASPM. Flags settings that hurt stability/performance and **suggests** the fix command
-(read-only per D9).
+PCIe ASPM. Flags settings that hurt stability/performance and **suggests** the fix command.
+Also includes Steam library/game detection (the D12 "pick a game" foundation) and, per D22,
+a **one-click apply** for the runtime-reversible tunables (governor, persistence, ASPM,
+swappiness, THP) plus one-click install of optional tools (GameMode/MangoHud/cpupower).

 ### M8 — Alerting
 Threshold + event alerts (desktop notification / sound / log) on overheat, throttle,
@@ -0,0 +1,117 @@
+#!/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" \
+          "$DATA_HOME/icons/hicolor/scalable/apps/rigdoctor.svg"
+    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"
+
+# Install the app icon (for the dock/launcher); fall back to a stock icon.
+ICON_NAME=utilities-system-monitor
+ICON_SRC=$("$VENV/bin/python" -c "import os, rigdoctor.gui as g; print(os.path.join(os.path.dirname(g.__file__), 'assets', 'rigdoctor.svg'))" 2>/dev/null || true)
+if [ -n "$ICON_SRC" ] && [ -f "$ICON_SRC" ]; then
+    ICON_DST="$DATA_HOME/icons/hicolor/scalable/apps/rigdoctor.svg"
+    mkdir -p "$(dirname "$ICON_DST")"
+    cp "$ICON_SRC" "$ICON_DST"
+    ICON_NAME=rigdoctor
+    command -v gtk-update-icon-cache >/dev/null 2>&1 && gtk-update-icon-cache -qtf "$DATA_HOME/icons/hicolor" 2>/dev/null || true
+fi
+
+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=$ICON_NAME
+Terminal=false
+Categories=System;Monitor;Utility;
+StartupWMClass=rigdoctor
+EOF
+command -v update-desktop-database >/dev/null 2>&1 && update-desktop-database "$DESKTOP_DIR" 2>/dev/null || true
+
+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
@@ -0,0 +1,25 @@
+#!/usr/bin/env sh
+# Auto-set the next version from Conventional Commits (git-cliff), per D21.
+# Run after committing your feat:/fix: changes; it updates __init__.py + pyproject.toml.
+# Then update CHANGELOG.md, commit as `chore(release): vX.Y.Z`, and push (CI tags + releases).
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+cd "$ROOT"
+
+command -v git-cliff >/dev/null 2>&1 || { echo "git-cliff not found. Install: pip install git-cliff"; exit 1; }
+
+NEXT=$(git-cliff --bumped-version | sed 's/^v//')
+[ -n "$NEXT" ] || { echo "Could not compute the next version."; exit 1; }
+
+python3 - "$NEXT" <<'PY'
+import pathlib, re, sys
+version = sys.argv[1]
+init = pathlib.Path("src/rigdoctor/__init__.py")
+init.write_text(re.sub(r'__version__ = "[^"]+"', f'__version__ = "{version}"', init.read_text()))
+proj = pathlib.Path("pyproject.toml")
+proj.write_text(re.sub(r'(?m)^version = "[^"]+"', f'version = "{version}"', proj.read_text(), count=1))
+PY
+
+echo "Set version to $NEXT."
+echo "Next: add a '## [$NEXT]' CHANGELOG section, then commit as 'chore(release): v$NEXT'."
@@ -0,0 +1,20 @@
+#!/usr/bin/env sh
+# Regenerate CHANGELOG.md from Conventional Commits using git-cliff (D20).
+# Install once:  pip install git-cliff   (ships prebuilt binaries)
+# Usage:         packaging/changelog.sh [--tag vX.Y.Z]
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+cd "$ROOT"
+
+command -v git-cliff >/dev/null 2>&1 || {
+    echo "git-cliff not found. Install it: pip install git-cliff"
+    exit 1
+}
+
+if [ "${1:-}" = "--tag" ] && [ -n "${2:-}" ]; then
+    git-cliff --tag "$2" -o CHANGELOG.md
+else
+    git-cliff -o CHANGELOG.md
+fi
+echo "Wrote CHANGELOG.md"
@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+# Build the self-extracting .run installer (delegates to make_run.py — no makeself).
+exec python3 "$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)/make_run.py" "$@"
@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Build a dependency-free self-extracting .run installer (no makeself).
+
+Produces dist/rigdoctor-<version>-installer.run: a POSIX shell stub with an appended
+tar.gz of the wheel + install.sh. Running it extracts to a temp dir and runs install.sh.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import subprocess
+import sys
+import tarfile
+import tomllib
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+MARKER = "__RIGDOCTOR_ARCHIVE__"
+
+STUB = f"""#!/bin/sh
+# RigDoctor self-extracting installer. Extracts the embedded archive and runs install.sh.
+set -eu
+SKIP=$(awk '/^{MARKER}$/ {{ print NR + 1; exit 0 }}' "$0")
+TMP=$(mktemp -d)
+tail -n +"$SKIP" "$0" | tar -xz -C "$TMP"
+sh "$TMP/install.sh" "$@"
+RET=$?
+rm -rf "$TMP"
+exit $RET
+{MARKER}
+"""
+
+
+def main() -> int:
+    version = tomllib.loads((ROOT / "pyproject.toml").read_text())["project"]["version"]
+    dist = ROOT / "dist"
+    dist.mkdir(exist_ok=True)
+
+    wheel = dist / f"rigdoctor-{version}-py3-none-any.whl"
+    if not wheel.exists():
+        subprocess.run([sys.executable, "-m", "build", "--wheel"], cwd=ROOT, check=True)
+    if not wheel.exists():
+        print(f"wheel not found: {wheel}", file=sys.stderr)
+        return 1
+
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tar:
+        tar.add(wheel, arcname=wheel.name)
+        tar.add(ROOT / "install.sh", arcname="install.sh")
+
+    out = dist / f"rigdoctor-{version}-installer.run"
+    with open(out, "wb") as f:
+        f.write(STUB.encode())
+        f.write(buf.getvalue())
+    os.chmod(out, 0o755)
+    print(f"Built {out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

 [project]
 name = "rigdoctor"
-version = "0.0.2"
+version = "0.14.0"
 description = "Modular hardware monitoring & crash diagnostics for Linux gamers."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -13,7 +13,7 @@ requires-python = ">=3.11"
 dependencies = []

 [project.optional-dependencies]
-gui = ["PySide6"]
+gui = ["PySide6", "pyte"]

 [project.scripts]
 rigdoctor = "rigdoctor.cli:main"
@@ -21,3 +21,6 @@ rigdoctor-gui = "rigdoctor.gui.app:main"

 [tool.setuptools.packages.find]
 where = ["src"]
+
+[tool.setuptools.package-data]
+rigdoctor = ["gui/assets/*.svg"]
@@ -1,3 +1,3 @@
 """RigDoctor — modular hardware monitoring & crash diagnostics for Linux gamers."""

-__version__ = "0.0.2"
+__version__ = "0.14.0"
@@ -86,6 +86,7 @@ def cmd_record_run(args) -> int:
        max_bytes=cfg["log_max_bytes"],
        backups=cfg["log_backups"],
        status_path=config.STATUS_FILE,
+        game=getattr(args, "game", None),
    )

    def _handle(_sig, _frame):
@@ -164,9 +165,337 @@ 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, _notes = 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, notes = 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 notes:
+        print("\nWhat's new:\n" + "\n".join("  " + ln for ln in notes.splitlines()) + "\n")
+    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_uninstall(args) -> int:
+    from .core import uninstall as uninstaller
+
+    scope = "everything (app + settings, token, and logs)" if args.purge else "the app (settings/logs kept)"
+    if not args.yes:
+        try:
+            reply = input(f"Uninstall RigDoctor — remove {scope}? [y/N] ").strip().lower()
+        except EOFError:
+            reply = "n"
+        if reply not in ("y", "yes"):
+            print("Aborted.")
+            return 1
+    uninstaller.uninstall(purge=args.purge)
+    print("Uninstalling… RigDoctor will be removed momentarily.")
+    return 0
+
+
+def cmd_share_serve(args) -> int:
+    from .core import share
+
+    return share.serve(host=args.host, port=args.port)
+
+
+def cmd_collect_priv(args) -> int:
+    """Internal: emit root-only data (SMART + dmidecode) as JSON, run via pkexec at launch."""
+    from dataclasses import asdict
+
+    from .core.health import check_smart
+    from .core.inventory import _dmidecode
+
+    data = {"smart": [asdict(f) for f in check_smart()], "dmidecode": _dmidecode()}
+    print(json.dumps(data))
+    return 0
+
+
+def cmd_inventory(args) -> int:
+    from .core import inventory
+
+    sections = inventory.collect()
+    if args.json:
+        text = inventory.render_json(sections)
+    elif args.markdown:
+        text = inventory.render_markdown(sections)
+    else:
+        text = inventory.render_text(sections)
+    if args.output:
+        Path(args.output).write_text(text)
+        print(f"Wrote {args.output}")
+    else:
+        print(text)
+    return 0
+
+
 def cmd_report(args) -> int:
-    print("`report` (M4 health report) is not implemented yet — next on the roadmap.")
-    return 2
+    from dataclasses import asdict
+
+    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 _resolve_game(args) -> str | None:
+    """Game name from --game, or looked up from --appid via the Steam scan."""
+    if getattr(args, "game", None):
+        return args.game
+    if getattr(args, "appid", None):
+        from .core import steam
+
+        for g in steam.scan_games(steam.selected_library_paths()):
+            if g.appid == str(args.appid):
+                return g.name
+        return None
+    return None
+
+
+def cmd_diagnose(args) -> int:
+    from .core import diagnostic, reccontrol, steam
+
+    sub = args.diagnose_cmd or "status"
+
+    if sub == "start":
+        if reccontrol.running_pid():
+            print("A capture is already running — finish it with: rigdoctor diagnose finish")
+            return 1
+        game = _resolve_game(args)
+        if game is None and (args.game or args.appid):
+            print("Couldn't match that game in your selected Steam libraries.")
+            return 1
+        if game is None:
+            games = steam.cached_games() or steam.scan_games(steam.selected_library_paths())
+            if games:
+                print("Pick a game to focus on, then re-run with --game:")
+                for g in games:
+                    print(f"  --game {g.name!r}")
+            else:
+                print("No games detected. Select a library: rigdoctor games libraries --all")
+            return 1
+        pid = diagnostic.start(game=game, interval=args.interval)
+        time.sleep(1.0)
+        if pid and reccontrol.pid_alive(pid):
+            print(f"Diagnostic capture started for {game!r} (pid {pid}).")
+            print("  Play your game. When you're done (or after a crash + reboot):")
+            print("    rigdoctor diagnose finish")
+            return 0
+        print(f"Capture failed to start; see {config.SPAWN_LOG}")
+        return 1
+
+    if sub == "status":
+        status = diagnostic.active()
+        if not status:
+            print("No diagnostic capture is running.")
+            return 0
+        game = status.get("game") or "—"
+        print(f"Capturing for {game!r}: {status.get('samples', 0)} samples"
+              + (" · GPU-lost seen" if status.get("gpu_lost") else ""))
+        return 0
+
+    # finish
+    if not reccontrol.running_pid() and not config.DIAG_LOG.exists():
+        print("No diagnostic to analyze. Start one with: rigdoctor diagnose start --game <name>")
+        return 1
+    print("Stopping capture and analyzing…\n")
+    result = diagnostic.finish(last_n=args.last)
+    from .render import render_health, render_summary
+
+    if result.game:
+        print(f"Diagnostic — {result.game}\n")
+    print(render_summary(result.summary, log_path=config.DIAG_LOG))
+    print("\n" + render_health(result.findings, title="Findings"))
+    return 0
+
+
+def cmd_gameenv(args) -> int:
+    from dataclasses import asdict
+
+    from .core.gameenv import run_gameenv_checks
+    from .render import render_health
+
+    findings = run_gameenv_checks()
+    if args.json:
+        print(json.dumps([asdict(f) for f in findings], indent=2, ensure_ascii=False))
+    else:
+        print(render_health(findings, title="Gaming environment"))
+    return 0
+
+
+def cmd_games(args) -> int:
+    from .core import steam
+
+    selected = steam.selected_library_paths()
+    if not selected:
+        print("No Steam libraries selected to scan.")
+        print("  See them with:   rigdoctor games libraries")
+        print("  Then enable one: rigdoctor games libraries --enable <path>  (or --all)")
+        return 1
+    result = steam.rescan()
+    if args.json:
+        from dataclasses import asdict
+
+        print(json.dumps({
+            "scanned_at": result.scanned_at,
+            "new_appids": result.new_appids,
+            "games": [asdict(g) for g in result.games],
+        }, indent=2, ensure_ascii=False))
+        return 0
+    if not result.games:
+        print("No games found in the selected Steam libraries.")
+        return 0
+    new = set(result.new_appids)
+    print(f"{len(result.games)} game(s) across {len(selected)} librar(y/ies):\n")
+    for g in result.games:
+        flag = " NEW" if g.appid in new else ""
+        print(f"  {g.name:<48} {steam.human_size(g.size_bytes):>9}{flag}")
+    if new:
+        print(f"\n{len(new)} newly-installed since the last scan.")
+    return 0
+
+
+def cmd_games_libraries(args) -> int:
+    from .core import steam
+
+    discovered = steam.discover_libraries()
+    selected = {os.path.realpath(p) for p in steam.selected_library_paths()}
+
+    # --all / --enable / --disable adjust the selection, then we list the result.
+    if args.all or args.enable or args.disable:
+        if args.all:
+            selected = {lib.path for lib in discovered}
+        for raw in args.enable or []:
+            selected.add(os.path.realpath(os.path.expanduser(raw)))
+        for raw in args.disable or []:
+            selected.discard(os.path.realpath(os.path.expanduser(raw)))
+        config.update_config(steam_libraries=sorted(selected))
+
+    if not discovered:
+        print("No Steam libraries detected (is Steam installed?).")
+        return 1
+    if args.json:
+        print(json.dumps([
+            {"path": lib.path, "label": lib.label, "selected": lib.path in selected,
+             "games": len(steam.scan_library(lib.path))}
+            for lib in discovered
+        ], indent=2, ensure_ascii=False))
+        return 0
+    print("Steam libraries (checked = scanned for games):\n")
+    for lib in discovered:
+        mark = "x" if lib.path in selected else " "
+        count = len(steam.scan_library(lib.path))
+        label = f"  [{lib.label}]" if lib.label else ""
+        print(f"  [{mark}] {lib.path}{label}  ({count} games)")
+    return 0


 def build_parser() -> argparse.ArgumentParser:
@@ -188,12 +517,32 @@ 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)
+
+    unin = sub.add_parser("uninstall", help="remove the user-local install")
+    unin.add_argument("--purge", action="store_true", help="also remove settings, token, and logs")
+    unin.add_argument("-y", "--yes", action="store_true", help="don't ask for confirmation")
+    unin.set_defaults(func=cmd_uninstall)
+
    rec = sub.add_parser("record", help="crash-capture logger (M3)")
    rec_sub = rec.add_subparsers(dest="record_cmd", required=True)

    run_p = rec_sub.add_parser("run", help="run the capture loop in the foreground (systemd-friendly)")
    run_p.add_argument("-n", "--interval", type=float, default=None, help="sampling interval (s)")
    run_p.add_argument("-o", "--out", default=None, help="log file path")
+    run_p.add_argument("--game", default=None, help="tag the capture with a game name (M6/diagnose)")
    run_p.set_defaults(func=cmd_record_run)

    start_p = rec_sub.add_parser("start", help="start recording in the background")
@@ -209,7 +558,53 @@ 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)
+
+    cp = sub.add_parser("collect-priv", help=argparse.SUPPRESS)  # internal: run via pkexec
+    cp.set_defaults(func=cmd_collect_priv)
+
+    share_p = sub.add_parser("share", help="session sharing (M12)")
+    share_sub = share_p.add_subparsers(dest="share_cmd", required=True)
+    serve_p = share_sub.add_parser("serve", help="serve a read-only live view (token-gated)")
+    serve_p.add_argument("--host", default="127.0.0.1", help="bind address (use 0.0.0.0 + a tunnel for remote)")
+    serve_p.add_argument("--port", type=int, default=8765, help="port")
+    serve_p.set_defaults(func=cmd_share_serve)
+
+    inv = sub.add_parser("inventory", help="system inventory (M5): export hardware/OS details")
+    inv.add_argument("--json", action="store_true", help="output JSON")
+    inv.add_argument("--markdown", action="store_true", help="output Markdown (for forum/bug reports)")
+    inv.add_argument("-o", "--output", default=None, help="write to a file instead of stdout")
+    inv.set_defaults(func=cmd_inventory)
+
+    games_p = sub.add_parser("games", help="Steam game & library detection (M6)")
+    games_p.add_argument("--json", action="store_true", help="output JSON")
+    games_p.set_defaults(func=cmd_games)
+    games_sub = games_p.add_subparsers(dest="games_cmd")
+    lib_p = games_sub.add_parser("libraries", help="list/select Steam libraries to scan")
+    lib_p.add_argument("--enable", action="append", metavar="PATH", help="scan this library (repeatable)")
+    lib_p.add_argument("--disable", action="append", metavar="PATH", help="stop scanning this library (repeatable)")
+    lib_p.add_argument("--all", action="store_true", help="scan all detected libraries")
+    lib_p.add_argument("--json", action="store_true", help="output JSON")
+    lib_p.set_defaults(func=cmd_games_libraries)
+
+    env_p = sub.add_parser("gameenv", help="gaming environment checks (M6): flag stability/perf settings")
+    env_p.add_argument("--json", action="store_true", help="output JSON instead of text")
+    env_p.set_defaults(func=cmd_gameenv)
+
+    diag_p = sub.add_parser("diagnose", help="guided diagnostic: capture while gaming, then analyze")
+    diag_sub = diag_p.add_subparsers(dest="diagnose_cmd")
+    diag_start = diag_sub.add_parser("start", help="start a focused capture for a game")
+    diag_start.add_argument("--game", default=None, help="game name to focus on")
+    diag_start.add_argument("--appid", default=None, help="Steam appid to focus on (resolved to a name)")
+    diag_start.add_argument("-n", "--interval", type=float, default=None, help="sampling interval (s)")
+    diag_start.set_defaults(func=cmd_diagnose)
+    diag_sub.add_parser("status", help="show the in-progress diagnostic").set_defaults(func=cmd_diagnose)
+    diag_finish = diag_sub.add_parser("finish", help="stop the capture and analyze it")
+    diag_finish.add_argument("--last", type=int, default=10, help="recent samples to show")
+    diag_finish.set_defaults(func=cmd_diagnose)
+    diag_p.set_defaults(func=cmd_diagnose, diagnose_cmd=None, last=10)
    return p


@@ -3,6 +3,8 @@
 from __future__ import annotations

 import os
+import shutil
+import subprocess
 from pathlib import Path

 APP = "rigdoctor"
@@ -21,14 +23,134 @@ CONFIG_FILE = CONFIG_DIR / "config.toml"

 # Crash-capture logger (M3)
 LOG_FILE = LOG_DIR / "capture.jsonl"
+# Guided diagnostic (M6/D12): a focused capture writes here, separate from the always-on
+# crash log, so its report covers only that session's window.
+DIAG_LOG = LOG_DIR / "diagnostic.jsonl"
 STATUS_FILE = STATE_DIR / "recorder.json"
 PID_FILE = STATE_DIR / "recorder.pid"
 SPAWN_LOG = STATE_DIR / "recorder.out"

+# Gaming environment / game detection (M6) — cached Steam game scan (mutable state,
+# not config: refreshed by the background scan on every launch).
+GAMES_FILE = STATE_DIR / "games.json"
+
+# 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
    "log_backups": 10,            # keep this many rotated segments (bounds disk use)
+    "update_check_minutes": 30,   # re-check for updates this often while running (0 = off)
+    "elevate_on_launch": True,    # GUI asks for the password once at launch (SMART/dmidecode)
+    "alerts_enabled": True,       # desktop notifications on overheat / GPU-lost / new version
+    "gpu_temp_alert": 90.0,       # °C — alert when GPU reaches this
+    "cpu_temp_alert": 95.0,       # °C — alert when CPU reaches this
+    "relay_url": "wss://rigdoctor.jesseyvanofferen.com",  # session-sharing relay (M12)
+    "steam_libraries": [],        # Steam library paths to scan for games (M6); empty = none picked yet
 }


@@ -44,3 +166,29 @@ def load_config() -> dict:
    except Exception:
        pass
    return cfg
+
+
+def _toml_value(value) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return repr(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ", ".join(_toml_value(v) for v in value) + "]"
+    return '"' + str(value).replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def save_config(values: dict) -> None:
+    """Write a flat config.toml (stdlib has no TOML writer)."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    lines = ["# RigDoctor config — edit in the app (Notifications) or here."]
+    lines += [f"{key} = {_toml_value(value)}" for key, value in values.items()]
+    CONFIG_FILE.write_text("\n".join(lines) + "\n")
+
+
+def update_config(**changes) -> dict:
+    """Merge changes into the current effective config and persist them."""
+    cfg = load_config()
+    cfg.update(changes)
+    save_config(cfg)
+    return cfg
@@ -0,0 +1,109 @@
+"""Desktop alerts (M8): notify on overheat / GPU-lost / new version via notify-send.
+
+Edge-triggered: an alert fires when a condition becomes true (not every sample), and
+can fire again only after it has cleared and a cooldown has passed — so a hot GPU or a
+1-Hz sample loop doesn't spam notifications. Degrades to a no-op if notify-send is absent.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import time
+from pathlib import Path
+
+from ..config import DATA_DIR
+from .sample import Sample
+
+APP_NAME = "RigDoctor"
+_STOCK_ICON = "utilities-system-monitor"
+# The RigDoctor icon, so notifications match the app/dock icon. Prefer the copy that
+# desktop integration installs into the icon theme (~/.local/share/icons/...); fall back to
+# the bundled asset for source/dev runs, then to a stock icon if neither is present.
+_INSTALLED_ICON = DATA_DIR.parent / "icons" / "hicolor" / "scalable" / "apps" / "rigdoctor.svg"
+_BUNDLED_ICON = Path(__file__).parents[1] / "gui" / "assets" / "rigdoctor.svg"
+
+
+def available() -> bool:
+    return shutil.which("notify-send") is not None
+
+
+def _icon() -> str:
+    """Resolve the notification icon at call time (the themed copy may be installed late)."""
+    for path in (_INSTALLED_ICON, _BUNDLED_ICON):
+        try:
+            if path.exists():
+                return str(path)
+        except OSError:
+            pass
+    return _STOCK_ICON
+
+
+def notify(title: str, message: str, urgency: str = "normal") -> bool:
+    """Send a desktop notification (best-effort). urgency: low|normal|critical."""
+    if not available():
+        return False
+    try:
+        subprocess.run(
+            ["notify-send", "-a", APP_NAME, "-u", urgency, "-i", _icon(), title, message],
+            timeout=10,
+            check=False,
+        )
+        return True
+    except (subprocess.SubprocessError, OSError):
+        return False
+
+
+class AlertMonitor:
+    """Evaluate samples and raise edge-triggered desktop alerts."""
+
+    def __init__(self, gpu_temp: float = 90.0, cpu_temp: float = 95.0, cooldown: float = 300.0):
+        self.gpu_temp = gpu_temp
+        self.cpu_temp = cpu_temp
+        self.cooldown = cooldown
+        self.enabled = True
+        self._active: dict[str, bool] = {}
+        self._last: dict[str, float] = {}
+
+    def _fire(self, key: str, title: str, message: str, urgency: str = "critical") -> None:
+        if self._active.get(key):
+            return  # already alerting; wait until it clears
+        now = time.time()
+        if now - self._last.get(key, 0.0) < self.cooldown:
+            return
+        self._active[key] = True
+        self._last[key] = now
+        notify(title, message, urgency)
+
+    def _clear(self, key: str) -> None:
+        self._active[key] = False
+
+    def check(self, sample: Sample) -> None:
+        if not self.enabled:
+            return
+        gpu_t = next(
+            (r.value for r in sample.readings
+             if r.source == "gpu" and r.metric == "temp" and r.label == "" and r.value is not None),
+            None,
+        )
+        if gpu_t is not None:
+            if gpu_t >= self.gpu_temp:
+                self._fire("gpu_temp", "GPU overheating", f"GPU at {gpu_t:.0f} °C")
+            else:
+                self._clear("gpu_temp")
+
+        cpu_temps = [r.value for r in sample.readings
+                     if r.source == "cpu" and r.metric == "temp" and r.value is not None]
+        if cpu_temps:
+            cpu_t = max(cpu_temps)
+            if cpu_t >= self.cpu_temp:
+                self._fire("cpu_temp", "CPU overheating", f"CPU at {cpu_t:.0f} °C")
+            else:
+                self._clear("cpu_temp")
+
+        lost = any(r.source == "gpu" and r.metric == "status" and r.label == "query-timeout"
+                   for r in sample.readings)
+        if lost:
+            self._fire("gpu_lost", "GPU not responding", "nvidia-smi query timed out — the GPU may have dropped")
+        else:
+            self._clear("gpu_lost")
@@ -0,0 +1,67 @@
+"""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", ("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", ("dmidecode",), "dmidecode",
+    ),
+    Component(
+        "pciutils", "pciutils", "Diagnostics",
+        "PCIe topology + GPU detection (lspci)", ("pciutils",), "lspci",
+    ),
+    Component(
+        "libnotify", "Desktop notifications", "Monitoring",
+        "Desktop alert notifications", ("libnotify-bin",), "notify-send",
+    ),
+    Component(
+        "libsecret", "Encrypted token storage", "Updates",
+        "Store the update token in the OS keyring, encrypted", ("libsecret-tools",), "secret-tool",
+    ),
+    Component(
+        "gamemode", "Feral GameMode", "Gaming",
+        "Auto-applies performance tweaks (CPU governor, scheduling) while a game runs",
+        ("gamemode",), "gamemoderun",
+    ),
+    Component(
+        "mangohud", "MangoHud", "Gaming",
+        "In-game overlay for FPS, frame times, and temperatures", ("mangohud",), "mangohud",
+    ),
+    Component(
+        "cpupower", "cpupower", "Gaming",
+        "Read/set the CPU frequency governor (e.g. performance for gaming)",
+        ("linux-tools-common", "linux-tools-generic"), "cpupower",
+    ),
+)
+
+
+def by_id(component_id: str) -> Component | None:
+    """Look up a catalog component by its id (None if unknown)."""
+    return next((c for c in COMPONENTS if c.id == component_id), None)
@@ -0,0 +1,84 @@
+"""Guided diagnostic session (SPEC §4 / ARCHITECTURE §7.1): orchestrate M3 + M4.
+
+The seed use case, one flow: **pick a game** → **focused crash-capture** scoped to that
+session (M3, tagged with the game) → on **finish**, **scan & analyze** (M4 health report)
+over the captured window + system logs → return a prioritized result. This is not a new
+module — it's a single shared callable so the CLI, GUI, and tray run the identical flow.
+
+The capture is **manually bracketed** (start/finish) for now; auto start/stop on game launch
+(the D12 wrapper/watcher) plugs in here later without changing the result shape.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+from .. import config
+from . import reccontrol
+from .crashlog import Summary, summarize
+from .health import Finding
+
+
+@dataclass
+class DiagnosticResult:
+    game: str | None
+    summary: Summary           # capture window: peak temps/power, events, last samples (M3)
+    findings: list[Finding]    # health findings: Xid/SMART/driver/etc. (M4)
+
+
+def _clear_diag_log() -> None:
+    """Each diagnostic is a fresh focused capture — drop any previous session + segments."""
+    base = config.DIAG_LOG
+    for p in [base, *base.parent.glob(base.name + ".*")]:
+        try:
+            p.unlink()
+        except OSError:
+            pass
+
+
+def start(game: str | None = None, interval: float | None = None) -> int | None:
+    """Begin a focused capture, tagged with the game, into the dedicated diagnostic log.
+    Returns the pid, or None if a capture is already running."""
+    if reccontrol.running_pid():
+        return None
+    _clear_diag_log()
+    return reccontrol.start_background(interval=interval, out=str(config.DIAG_LOG), game=game)
+
+
+def is_running() -> bool:
+    return reccontrol.running_pid() is not None
+
+
+def active() -> dict | None:
+    """Status of the in-progress session (running flag, game, samples), or None if idle."""
+    if not is_running():
+        return None
+    return reccontrol.read_status()
+
+
+def _await_stopped(timeout: float = 6.0) -> None:
+    deadline = time.monotonic() + timeout
+    while reccontrol.running_pid() and time.monotonic() < deadline:
+        time.sleep(0.1)
+
+
+def _game_from_summary(summary: Summary) -> str | None:
+    """Recover the focused game from the log's 'game' event (survives a crash + reboot)."""
+    for _ts, kind, detail in reversed(summary.events):
+        if kind == "game" and detail:
+            return detail
+    return None
+
+
+def finish(last_n: int = 10, log_path=None) -> DiagnosticResult:
+    """Stop the capture (if running), summarize the window, and run the health report."""
+    from .health import run_health_checks
+
+    reccontrol.stop_background()
+    _await_stopped()
+    path = log_path or config.DIAG_LOG
+    summary = summarize(path, last_n=last_n)
+    game = _game_from_summary(summary) or (reccontrol.read_status() or {}).get("game")
+    findings = run_health_checks()
+    return DiagnosticResult(game=game, summary=summary, findings=findings)
@@ -0,0 +1,51 @@
+"""Session privilege elevation.
+
+At GUI launch the app asks for the password once (pkexec) and collects the data that
+needs root — SMART health + dmidecode (board/BIOS/RAM) — caching it for the session so
+Health and Inventory can always show the full picture without per-action prompts.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+
+_privileged: dict | None = None
+
+
+def privileged() -> dict | None:
+    """Cached root-collected data ({"smart": [...], "dmidecode": {...}}), or None."""
+    return _privileged
+
+
+def set_privileged(data: dict | None) -> None:
+    global _privileged
+    _privileged = data
+
+
+def available() -> bool:
+    return shutil.which("pkexec") is not None and os.geteuid() != 0
+
+
+def _cli() -> list[str]:
+    candidate = os.path.join(os.path.dirname(sys.executable), "rigdoctor")
+    return [candidate] if os.path.exists(candidate) else [sys.executable, "-m", "rigdoctor"]
+
+
+def collect_via_pkexec(timeout: float = 120.0) -> dict | None:
+    """Run one elevated collection (single password prompt). None if unavailable/cancelled."""
+    if not available():
+        return None
+    try:
+        proc = subprocess.run(
+            ["pkexec", *_cli(), "collect-priv"],
+            capture_output=True, text=True, timeout=timeout,
+        )
+        if proc.returncode == 0 and proc.stdout.strip():
+            return json.loads(proc.stdout)
+    except (subprocess.SubprocessError, OSError, ValueError):
+        pass
+    return None
@@ -0,0 +1,177 @@
+"""Apply runtime-reversible system tunables (M6) — a limited, consent-gated exception to
+the read-only stance (D9, amended by D22).
+
+Only safe settings that take effect immediately, need no reboot, and revert on reboot are
+applyable here: CPU governor, NVIDIA persistence mode, PCIe ASPM policy, vm.swappiness, and
+Transparent HugePages. Each is set by a single privileged command (one pkexec prompt). The
+chosen value is validated against the live options before building the command, and writes go
+to sysfs / procfs (or `nvidia-smi`) — never the GRUB cmdline or a persistent config file.
+Riskier fixes (GRUB-based PCIe ASPM-off, CPU mitigations) stay suggestion-only.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class Tunable:
+    id: str
+    label: str            # e.g. "CPU governor"
+    options: list[str]    # selectable values (live, from the system)
+    current: str | None   # the value in effect now (preselect this in the dropdown)
+    note: str = ""        # caveat shown by the control, e.g. "resets on reboot"
+
+
+def _read(path: str) -> str | None:
+    try:
+        return Path(path).read_text()
+    except OSError:
+        return None
+
+
+def _bracketed(text: str) -> tuple[list[str], str | None]:
+    """Parse a sysfs 'a [b] c' enum into (options, active)."""
+    options = [tok.strip("[]") for tok in text.split()]
+    active = next((tok.strip("[]") for tok in text.split() if tok.startswith("[")), None)
+    return options, active
+
+
+# --- individual tunables: a state reader + a command builder per id -------------------
+
+_GOV = "/sys/devices/system/cpu"
+
+
+def _cpu_governor() -> Tunable | None:
+    cur = _read(f"{_GOV}/cpu0/cpufreq/scaling_governor")
+    if cur is None:
+        return None
+    avail = _read(f"{_GOV}/cpu0/cpufreq/scaling_available_governors")
+    options = avail.split() if avail and avail.strip() else ["performance", "powersave", "schedutil"]
+    return Tunable("cpu_governor", "CPU governor", options, cur.strip(), "applies now; resets on reboot")
+
+
+def _cpu_governor_cmd(value: str) -> list[str]:
+    return ["/bin/sh", "-c",
+            f'for f in {_GOV}/cpu*/cpufreq/scaling_governor; do echo {shlex.quote(value)} > "$f"; done']
+
+
+def _nvidia_persistence() -> Tunable | None:
+    if shutil.which("nvidia-smi") is None:
+        return None
+    try:
+        proc = subprocess.run(
+            ["nvidia-smi", "--query-gpu=persistence_mode", "--format=csv,noheader"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (subprocess.SubprocessError, OSError):
+        return None
+    state = proc.stdout.strip().splitlines()[0].strip().lower() if proc.stdout.strip() else ""
+    current = "Enabled" if state.startswith("enabled") else ("Disabled" if state.startswith("disabled") else None)
+    return Tunable("nvidia_persistence", "NVIDIA persistence mode", ["Enabled", "Disabled"], current,
+                   "resets on reboot (enable nvidia-persistenced to persist)")
+
+
+def _nvidia_persistence_cmd(value: str) -> list[str]:
+    return ["nvidia-smi", "-pm", "1" if value == "Enabled" else "0"]
+
+
+def _pcie_aspm() -> Tunable | None:
+    text = _read("/sys/module/pcie_aspm/parameters/policy")
+    if not text:
+        return None
+    options, active = _bracketed(text)
+    return Tunable("pcie_aspm", "PCIe ASPM policy", options, active, "applies now; resets on reboot")
+
+
+def _pcie_aspm_cmd(value: str) -> list[str]:
+    return ["/bin/sh", "-c", f'echo {shlex.quote(value)} > /sys/module/pcie_aspm/parameters/policy']
+
+
+def _swappiness() -> Tunable | None:
+    text = _read("/proc/sys/vm/swappiness")
+    if text is None or not text.strip().isdigit():
+        return None
+    cur = text.strip()
+    options = ["0", "10", "30", "60", "100"]
+    if cur not in options:
+        options = sorted(set(options) | {cur}, key=int)
+    return Tunable("swappiness", "vm.swappiness", options, cur, "applies now; resets on reboot")
+
+
+def _swappiness_cmd(value: str) -> list[str]:
+    return ["/bin/sh", "-c", f'echo {shlex.quote(value)} > /proc/sys/vm/swappiness']
+
+
+def _thp() -> Tunable | None:
+    text = _read("/sys/kernel/mm/transparent_hugepage/enabled")
+    if not text:
+        return None
+    options, active = _bracketed(text)
+    return Tunable("thp", "Transparent HugePages", options, active, "applies now; resets on reboot")
+
+
+def _thp_cmd(value: str) -> list[str]:
+    return ["/bin/sh", "-c", f'echo {shlex.quote(value)} > /sys/kernel/mm/transparent_hugepage/enabled']
+
+
+_TUNABLES: dict[str, tuple[Callable[[], Tunable | None], Callable[[str], list[str]]]] = {
+    "cpu_governor": (_cpu_governor, _cpu_governor_cmd),
+    "nvidia_persistence": (_nvidia_persistence, _nvidia_persistence_cmd),
+    "pcie_aspm": (_pcie_aspm, _pcie_aspm_cmd),
+    "swappiness": (_swappiness, _swappiness_cmd),
+    "thp": (_thp, _thp_cmd),
+}
+
+
+# --- public API -----------------------------------------------------------------------
+
+def get_tunable(fix_id: str) -> Tunable | None:
+    """Live state (options + current value) for a fix id, or None if not applicable here."""
+    fns = _TUNABLES.get(fix_id)
+    return fns[0]() if fns else None
+
+
+def apply_command(fix_id: str, value: str) -> list[str] | None:
+    """The privileged command to set fix_id=value, or None if unknown/invalid.
+
+    The value is validated against the *live* options, so only a real, currently-available
+    setting can ever be turned into a command.
+    """
+    fns = _TUNABLES.get(fix_id)
+    if not fns:
+        return None
+    state = fns[0]()
+    if state is None or value not in state.options:
+        return None
+    return fns[1](value)
+
+
+def _elevate(cmd: list[str]) -> list[str]:
+    prog = shutil.which(cmd[0]) or cmd[0]  # pkexec needs an absolute program path
+    cmd = [prog, *cmd[1:]]
+    if os.geteuid() == 0:
+        return cmd
+    if shutil.which("pkexec"):
+        return ["pkexec", *cmd]
+    if shutil.which("sudo"):
+        return ["sudo", *cmd]
+    return cmd  # no escalation available — will likely fail, surfaced to the caller
+
+
+def apply(fix_id: str, value: str) -> tuple[int, str]:
+    """Apply fix_id=value via a single elevated command. Returns (exit_code, output)."""
+    cmd = apply_command(fix_id, value)
+    if cmd is None:
+        return (1, f"Unknown or unavailable setting: {fix_id}={value}")
+    try:
+        proc = subprocess.run(_elevate(cmd), capture_output=True, text=True, timeout=120)
+        return (proc.returncode, proc.stdout + proc.stderr)
+    except (subprocess.SubprocessError, OSError) as exc:
+        return (1, str(exc))
@@ -0,0 +1,271 @@
+"""Gaming environment checks (M6): evaluate system settings that affect gaming
+stability/performance and suggest the fix command — read-only (D9).
+
+Stdlib-only. Each check degrades gracefully (a missing file/tool yields no finding or an
+info finding, never an exception). The pure ``evaluate_*`` helpers are split from the IO
+that reads sysfs / runs tools, so they're unit-testable.
+
+Several checks target the seed case directly: an RTX 3070 falling off the PCIe bus under
+load (Xid 79). PCIe ASPM power-saving, NVIDIA persistence mode, and a power-saving CPU
+governor are the usual contributors to that class of drop-off / stutter.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from .health import INFO, OK, WARNING, Finding
+
+_ORDER = {"critical": 0, WARNING: 1, INFO: 2, OK: 3}
+
+
+def _read(path: str) -> str | None:
+    try:
+        return Path(path).read_text()
+    except OSError:
+        return None
+
+
+# --- PCIe ASPM (seed-case relevant) ---------------------------------------------------
+
+def _active_aspm(policy_text: str) -> str | None:
+    """The active ASPM policy is the bracketed token, e.g. '[default] performance ...'."""
+    m = re.search(r"\[(\w+)\]", policy_text)
+    return m.group(1) if m else None
+
+
+def evaluate_aspm(policy_text: str | None) -> Finding | None:
+    if not policy_text:
+        return None
+    active = _active_aspm(policy_text)
+    if active is None:
+        return None
+    if active in ("powersave", "powersupersave"):
+        return Finding(
+            WARNING, "PCIe", f"PCIe ASPM is in power-saving mode ({active})",
+            "Aggressive PCIe Active-State Power Management can cause the GPU to drop off the "
+            "bus under load (Xid 79) or stutter — the seed-case failure mode.",
+            "Set the policy to performance below (live), or for a permanent change add "
+            "`pcie_aspm=off` in GRUB, then `sudo update-grub` and reboot.",
+            fix="pcie_aspm",
+        )
+    if active == "performance":
+        return Finding(OK, "PCIe", "PCIe ASPM set to performance", "ASPM power-saving is disabled.",
+                       fix="pcie_aspm")
+    return Finding(
+        INFO, "PCIe", f"PCIe ASPM policy: {active}",
+        "ASPM is left to the kernel/BIOS default.",
+        "If you see GPU bus-drop events (Xid 79), set the policy to performance below.",
+        fix="pcie_aspm",
+    )
+
+
+def check_pcie_aspm() -> list[Finding]:
+    f = evaluate_aspm(_read("/sys/module/pcie_aspm/parameters/policy"))
+    return [f] if f else []
+
+
+# --- NVIDIA persistence mode (seed-case relevant) -------------------------------------
+
+def check_gpu_persistence() -> list[Finding]:
+    if shutil.which("nvidia-smi") is None:
+        return []
+    try:
+        proc = subprocess.run(
+            ["nvidia-smi", "--query-gpu=persistence_mode", "--format=csv,noheader"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (subprocess.SubprocessError, OSError):
+        return []
+    state = proc.stdout.strip().splitlines()[0].strip() if proc.stdout.strip() else ""
+    if state.lower().startswith("disabled"):
+        return [Finding(
+            INFO, "GPU", "NVIDIA persistence mode is off",
+            "The driver unloads when no client is attached, adding latency on first GPU "
+            "access and churning state between game launches.",
+            "Enable it below (per-boot), or enable the `nvidia-persistenced` service to "
+            "make it permanent.",
+            fix="nvidia_persistence",
+        )]
+    if state.lower().startswith("enabled"):
+        return [Finding(OK, "GPU", "NVIDIA persistence mode on", "The driver stays resident.",
+                        fix="nvidia_persistence")]
+    return []
+
+
+# --- CPU governor ---------------------------------------------------------------------
+
+def evaluate_governor(governors: set[str]) -> Finding | None:
+    if not governors:
+        return None
+    shown = ", ".join(sorted(governors))
+    if governors == {"performance"}:
+        return Finding(OK, "CPU", "CPU governor: performance", "CPUs run at full clocks under load.",
+                       fix="cpu_governor")
+    if "powersave" in governors:
+        return Finding(
+            WARNING, "CPU", f"CPU governor set to power-saving ({shown})",
+            "A powersave governor caps CPU frequency and can bottleneck frame times.",
+            "Set it to performance below (or install GameMode to switch it per-game).",
+            fix="cpu_governor",
+        )
+    return Finding(
+        INFO, "CPU", f"CPU governor: {shown}",
+        "A dynamic governor scales with load; usually fine.",
+        "For the most consistent frame pacing, set performance below (or use GameMode).",
+        fix="cpu_governor",
+    )
+
+
+def check_cpu_governor() -> list[Finding]:
+    govs: set[str] = set()
+    for p in Path("/sys/devices/system/cpu").glob("cpu*/cpufreq/scaling_governor"):
+        text = _read(str(p))
+        if text and text.strip():
+            govs.add(text.strip())
+    f = evaluate_governor(govs)
+    return [f] if f else []
+
+
+# --- GameMode / MangoHud --------------------------------------------------------------
+
+def check_gamemode() -> list[Finding]:
+    if shutil.which("gamemoderun") or shutil.which("gamemoded"):
+        return [Finding(
+            OK, "Tools", "Feral GameMode installed",
+            "GameMode can apply the performance governor and other tweaks while a game runs.",
+        )]
+    return [Finding(
+        INFO, "Tools", "GameMode not installed",
+        "GameMode auto-applies performance tweaks (governor, scheduling) for the duration of a game.",
+        "Install it: `sudo apt install gamemode`, then launch games with `gamemoderun %command%` "
+        "(or use a global Steam launch option).",
+        action="gamemode",
+    )]
+
+
+def check_mangohud() -> list[Finding]:
+    if shutil.which("mangohud"):
+        return [Finding(OK, "Tools", "MangoHud available", "In-game FPS/temps/frametime overlay is installed.")]
+    return [Finding(
+        INFO, "Tools", "MangoHud not installed",
+        "MangoHud overlays live FPS, frame times, and temps in-game — handy for spotting stutter.",
+        "Install it: `sudo apt install mangohud`, then launch with `mangohud %command%`.",
+        action="mangohud",
+    )]
+
+
+# --- vm.swappiness --------------------------------------------------------------------
+
+def evaluate_swappiness(value: int) -> Finding:
+    if value > 10:
+        return Finding(
+            INFO, "Memory", f"vm.swappiness is high ({value})",
+            "A high swappiness lets the kernel swap out memory eagerly, which can cause "
+            "hitching during gaming on systems with ample RAM.",
+            "Lower it below (e.g. 10); applies immediately.",
+            fix="swappiness",
+        )
+    return Finding(OK, "Memory", f"vm.swappiness is {value}", "Swapping is conservative.",
+                   fix="swappiness")
+
+
+def check_swappiness() -> list[Finding]:
+    text = _read("/proc/sys/vm/swappiness")
+    if text is None or not text.strip().isdigit():
+        return []
+    return [evaluate_swappiness(int(text.strip()))]
+
+
+# --- shader cache ---------------------------------------------------------------------
+
+def evaluate_shader_cache(env: dict) -> Finding:
+    disabled = (
+        env.get("__GL_SHADER_DISK_CACHE") == "0"
+        or env.get("MESA_SHADER_CACHE_DISABLE", "").lower() in ("1", "true")
+        or env.get("MESA_GLSL_CACHE_DISABLE", "").lower() in ("1", "true")
+    )
+    if disabled:
+        return Finding(
+            WARNING, "GPU", "Shader disk cache is disabled",
+            "With the shader cache off, shaders recompile every run — a common cause of "
+            "in-game stutter, especially on first encounters.",
+            "Unset the disabling variable (e.g. remove `__GL_SHADER_DISK_CACHE=0` / "
+            "`MESA_SHADER_CACHE_DISABLE`) from your environment / launch options.",
+        )
+    return Finding(OK, "GPU", "Shader disk cache enabled", "Compiled shaders are cached between runs (default).")
+
+
+def check_shader_cache() -> list[Finding]:
+    return [evaluate_shader_cache(os.environ)]
+
+
+# --- transparent hugepages / CPU mitigations (only when notable) ----------------------
+
+def check_thp() -> list[Finding]:
+    text = _read("/sys/kernel/mm/transparent_hugepage/enabled")
+    if not text:
+        return []
+    active = _active_aspm(text)  # same '[token]' format
+    if active == "never":
+        return [Finding(
+            INFO, "Memory", "Transparent HugePages disabled (never)",
+            "Some workloads benefit from THP; 'madvise' lets apps opt in without the downsides of 'always'.",
+            "Optional: set 'madvise' below; applies immediately.",
+            fix="thp",
+        )]
+    return []
+
+
+def check_mitigations() -> list[Finding]:
+    cmdline = _read("/proc/cmdline") or ""
+    if "mitigations=off" in cmdline:
+        return [Finding(
+            INFO, "CPU", "CPU security mitigations are disabled",
+            "`mitigations=off` recovers some CPU performance at the cost of CPU-vulnerability "
+            "protections — a deliberate trade-off, noted here for awareness.",
+            "Remove `mitigations=off` from the kernel cmdline to restore protections.",
+        )]
+    return []
+
+
+# --- Proton versions (informational) --------------------------------------------------
+
+def check_proton() -> list[Finding]:
+    from . import steam
+
+    try:
+        versions = steam.proton_versions()
+    except Exception:
+        versions = []
+    if not versions:
+        return []
+    return [Finding(
+        INFO, "Tools", f"Proton: {len(versions)} version(s) installed",
+        ", ".join(versions),
+        "Steam picks the Proton version per game (Properties → Compatibility); "
+        "Proton Experimental often has the latest fixes.",
+    )]
+
+
+# --- aggregate ------------------------------------------------------------------------
+
+def run_gameenv_checks() -> list[Finding]:
+    """Run all environment checks, sorted by severity (worst first)."""
+    findings: list[Finding] = []
+    findings += check_pcie_aspm()
+    findings += check_gpu_persistence()
+    findings += check_cpu_governor()
+    findings += check_gamemode()
+    findings += check_mangohud()
+    findings += check_swappiness()
+    findings += check_shader_cache()
+    findings += check_thp()
+    findings += check_mitigations()
+    findings += check_proton()
+    findings.sort(key=lambda f: _ORDER.get(f.severity, 9))
+    return findings
@@ -0,0 +1,257 @@
+"""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 = ""
+    action: str = ""  # optional: id of an installable catalog component (for an Install button)
+    fix: str = ""     # optional: id of an applyable runtime tunable (for an Apply dropdown, M6)
+
+
+# --- 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).
+
+    SMART needs root; if the session collected it via launch elevation, use that
+    instead of re-running smartctl (which would just report "needs root").
+    """
+    from . import elevation
+
+    findings: list[Finding] = []
+    findings += check_nvidia_driver()
+    findings += check_journal()
+    findings += check_journal_persistence()
+    priv = elevation.privileged()
+    if priv is not None and priv.get("smart") is not None:
+        findings += [Finding(**d) for d in priv["smart"]]
+    else:
+        findings += check_smart()
+    findings += check_live_temps()
+    findings.sort(key=lambda f: _ORDER.get(f.severity, 9))
+    return findings
@@ -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))
@@ -0,0 +1,206 @@
+"""System inventory (M5): collect hardware/OS details, exportable to Markdown/JSON.
+
+Stdlib + tools already used elsewhere (nvidia-smi, lspci, lsblk, dmidecode). Every
+probe degrades gracefully; board/BIOS/RAM-module details need dmidecode as root.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from .. import __version__
+from . import sysenv
+
+
+@dataclass
+class Section:
+    title: str
+    items: list[tuple[str, str]]
+
+
+def _run(cmd: list[str], timeout: float = 12.0) -> str:
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+        if proc.returncode == 0:
+            return proc.stdout
+    except (subprocess.SubprocessError, OSError):
+        pass
+    return ""
+
+
+def _system() -> Section:
+    u = os.uname()
+    return Section("System", [
+        ("Distro", sysenv.distro_name()),
+        ("Kernel", u.release),
+        ("Architecture", u.machine),
+        ("Hostname", u.nodename),
+        ("Python", platform.python_version()),
+        ("RigDoctor", __version__),
+    ])
+
+
+def _cpu() -> Section:
+    model = "?"
+    threads = 0
+    core_ids: set[tuple[str, str]] = set()
+    phys = "0"
+    try:
+        for line in Path("/proc/cpuinfo").read_text().splitlines():
+            if line.startswith("model name") and model == "?":
+                model = line.split(":", 1)[1].strip()
+            elif line.startswith("processor"):
+                threads += 1
+            elif line.startswith("physical id"):
+                phys = line.split(":", 1)[1].strip()
+            elif line.startswith("core id"):
+                core_ids.add((phys, line.split(":", 1)[1].strip()))
+    except OSError:
+        pass
+    items = [("Model", model)]
+    if core_ids:
+        items.append(("Cores", str(len(core_ids))))
+    items.append(("Threads", str(threads or os.cpu_count() or "?")))
+    return Section("CPU", items)
+
+
+def _firmware(dmi: dict) -> Section:
+    board = dmi.get("baseboard", {})
+    bios = dmi.get("bios", {})
+    items: list[tuple[str, str]] = []
+    if board:
+        items.append(("Motherboard", f"{board.get('Manufacturer', '')} {board.get('Product Name', '')}".strip()))
+    if bios:
+        items.append(("BIOS", f"{bios.get('Vendor', '')} {bios.get('Version', '')}".strip()))
+        if bios.get("Release Date"):
+            items.append(("BIOS date", bios["Release Date"]))
+    if not items:
+        items = [("Motherboard / BIOS", "run with admin (dmidecode needs root)")]
+    return Section("Firmware", items)
+
+
+def _memory(dmi: dict) -> Section:
+    items: list[tuple[str, str]] = []
+    try:
+        for line in Path("/proc/meminfo").read_text().splitlines():
+            if line.startswith("MemTotal"):
+                items.append(("Total", f"{int(line.split()[1]) / 1024 / 1024:.1f} GB"))
+                break
+    except (OSError, ValueError, IndexError):
+        pass
+    modules = dmi.get("memory", [])
+    if modules:
+        items.append(("Modules", str(len(modules))))
+        for i, m in enumerate(modules):
+            desc = " · ".join(p for p in (m.get("Size"), m.get("Type"), m.get("Speed"), m.get("Part Number")) if p)
+            items.append((f"Slot {i}", desc))
+    elif shutil.which("dmidecode"):
+        items.append(("Modules", "run with admin for module details"))
+    return Section("Memory", items)
+
+
+def _gpu() -> Section:
+    if shutil.which("nvidia-smi"):
+        out = _run([
+            "nvidia-smi",
+            "--query-gpu=name,driver_version,vbios_version,memory.total,pcie.link.gen.max,pcie.link.width.max",
+            "--format=csv,noheader",
+        ])
+        line = out.strip().splitlines()[0] if out.strip() else ""
+        if line:
+            cols = [c.strip() for c in line.split(",")]
+            keys = ["Name", "Driver", "VBIOS", "VRAM", "PCIe gen (max)", "PCIe width (max)"]
+            return Section("GPU", list(zip(keys, cols)))
+    out = _run(["lspci"])
+    gpus = [ln.split(":", 2)[-1].strip() for ln in out.splitlines()
+            if "VGA compatible controller" in ln or "3D controller" in ln]
+    return Section("GPU", [("Device", g) for g in gpus] or [("Device", "unknown")])
+
+
+def _storage() -> Section:
+    items: list[tuple[str, str]] = []
+    # TYPE first so MODEL (which can contain spaces) is the trailing field.
+    out = _run(["lsblk", "-dn", "-o", "TYPE,NAME,SIZE,MODEL"])
+    for line in out.strip().splitlines():
+        parts = line.split(None, 3)
+        if len(parts) < 3 or parts[0] != "disk":  # skip loop/zram/rom devices
+            continue
+        name, size = parts[1], parts[2]
+        model = parts[3] if len(parts) > 3 else ""
+        items.append((name, f"{model} ({size})".strip()))
+    return Section("Storage", items or [("Disks", "unknown")])
+
+
+def _display() -> Section:
+    return Section("Display", [
+        ("Session", os.environ.get("XDG_SESSION_TYPE", "unknown")),
+        ("Desktop", os.environ.get("XDG_CURRENT_DESKTOP") or os.environ.get("DESKTOP_SESSION", "unknown")),
+    ])
+
+
+def _dmidecode() -> dict:
+    if not shutil.which("dmidecode"):
+        return {}
+    out = _run(["dmidecode", "-t", "baseboard", "-t", "bios", "-t", "memory"], timeout=15)
+    if not out.strip():
+        return {}
+    result: dict = {"baseboard": {}, "bios": {}, "memory": []}
+    for block in out.split("Handle "):
+        lines = block.splitlines()
+        if len(lines) < 2:
+            continue
+        title = lines[1].strip()
+        kv: dict[str, str] = {}
+        for ln in lines[2:]:
+            if ln.startswith("\t") and ":" in ln:
+                key, _, value = ln.strip().partition(":")
+                kv[key.strip()] = value.strip()
+        if title == "Base Board Information":
+            result["baseboard"] = kv
+        elif title == "BIOS Information":
+            result["bios"] = kv
+        elif title == "Memory Device" and kv.get("Size") and kv["Size"] != "No Module Installed":
+            result["memory"].append(kv)
+    return result
+
+
+def collect() -> list[Section]:
+    from . import elevation
+
+    priv = elevation.privileged()
+    dmi = priv["dmidecode"] if (priv and priv.get("dmidecode") is not None) else _dmidecode()
+    return [_system(), _cpu(), _firmware(dmi), _memory(dmi), _gpu(), _storage(), _display()]
+
+
+def to_dict(sections: list[Section]) -> dict:
+    return {s.title: dict(s.items) for s in sections}
+
+
+def from_dict(data: dict) -> list[Section]:
+    return [Section(title, list(items.items())) for title, items in data.items()]
+
+
+def render_markdown(sections: list[Section]) -> str:
+    out = ["# RigDoctor system inventory", ""]
+    for s in sections:
+        out.append(f"## {s.title}")
+        out += [f"- **{k}:** {v}" for k, v in s.items]
+        out.append("")
+    return "\n".join(out).strip() + "\n"
+
+
+def render_text(sections: list[Section]) -> str:
+    blocks = []
+    for s in sections:
+        blocks.append("\n".join([s.title] + [f"  {k:<18} {v}" for k, v in s.items]))
+    return "\n\n".join(blocks)
+
+
+def render_json(sections: list[Section]) -> str:
+    return json.dumps(to_dict(sections), indent=2, ensure_ascii=False)
@@ -0,0 +1,59 @@
+"""A pseudo-terminal running the host's shell (M12, Tier 3 — host side).
+
+Spawns the user's login shell in a real PTY so interactive programs work over a shared
+session: vim, top, tab-completion, colours, Ctrl-C, and `sudo` (which prompts inside the
+PTY — the host types that password locally, so it's never sent to the guest). Runs as the
+host's own user — never elevated. Linux-only (uses `pty`/`termios`).
+"""
+
+from __future__ import annotations
+
+import fcntl
+import os
+import pty
+import signal
+import struct
+import termios
+
+
+class PtySession:
+    def __init__(self, rows: int = 24, cols: int = 80):
+        self.pid, self.master_fd = pty.fork()
+        if self.pid == 0:  # child: become the shell
+            os.environ["TERM"] = "xterm-256color"
+            shell = os.environ.get("SHELL", "/bin/bash")
+            try:
+                os.execvp(shell, [shell])
+            finally:
+                os._exit(1)
+        os.set_blocking(self.master_fd, False)
+        self.set_size(rows, cols)
+
+    def set_size(self, rows: int, cols: int) -> None:
+        try:
+            fcntl.ioctl(self.master_fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+        except OSError:
+            pass
+
+    def write(self, data: bytes) -> None:
+        try:
+            os.write(self.master_fd, data)
+        except OSError:
+            pass
+
+    def read(self, size: int = 65536) -> bytes:
+        try:
+            return os.read(self.master_fd, size)
+        except (BlockingIOError, OSError):
+            return b""
+
+    def close(self) -> None:
+        try:
+            os.close(self.master_fd)
+        except OSError:
+            pass
+        try:
+            os.kill(self.pid, signal.SIGHUP)
+            os.waitpid(self.pid, os.WNOHANG)
+        except (OSError, ChildProcessError, ProcessLookupError):
+            pass
@@ -38,7 +38,9 @@ def read_status() -> dict | None:
        return None


-def start_background(interval: float | None = None, out: str | None = None) -> int | None:
+def start_background(
+    interval: float | None = None, out: str | None = None, game: str | None = None
+) -> int | None:
    """Spawn a detached `record run`. Returns the child pid, or None if already running."""
    if running_pid():
        return None
@@ -48,6 +50,8 @@ def start_background(interval: float | None = None, out: str | None = None) -> i
        cmd += ["--interval", str(interval)]
    if out:
        cmd += ["--out", out]
+    if game:
+        cmd += ["--game", game]
    out_fh = open(config.SPAWN_LOG, "a")
    proc = subprocess.Popen(
        cmd,
@@ -27,12 +27,14 @@ class Recorder:
        backups: int = 10,
        status_path=None,
        sampler: Sampler | None = None,
+        game: str | None = None,
    ) -> None:
        self.interval = interval
        self.sampler = sampler or Sampler(available_sources())
        self.writer = CrashLogWriter(log_path, max_bytes, backups)
        self.log_path = Path(log_path)
        self.status_path = Path(status_path) if status_path else None
+        self.game = game or None
        self.samples = 0
        self._stop = threading.Event()
        self._gpu_lost = False
@@ -43,6 +45,8 @@ class Recorder:

    def run(self) -> None:
        self.writer.write_event("session-start", f"interval={self.interval:g}s")
+        if self.game:
+            self.writer.write_event("game", self.game)  # tag the focused-diagnostic target
        self._write_status(running=True)
        try:
            while not self._stop.is_set():
@@ -81,6 +85,7 @@ class Recorder:
            "samples": self.samples,
            "updated": time.time(),
            "gpu_lost": self._gpu_lost,
+            "game": self.game,
        }
        if sample is not None:
            data["latest"] = headline(sample)
@@ -0,0 +1,194 @@
+"""Session sharing (M12, Tier 2): a read-only live view over a local HTTP server.
+
+Serves the live sensor snapshot + health report + inventory, **read-only**, gated by a
+random share token. Bind to localhost for local testing, or to all interfaces behind a
+user-chosen tunnel (Tailscale / cloudflared / SSH) for remote help. No actions, no terminal.
+"""
+
+from __future__ import annotations
+
+import json
+import secrets
+from dataclasses import asdict
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+from .sampler import Sampler
+from .sources import available_sources
+
+_PAGE = """<!doctype html>
+<html><head><meta charset="utf-8"><title>RigDoctor — shared</title>
+<style>
+ body{background:#101216;color:#e6e8eb;font-family:system-ui,sans-serif;margin:0;padding:24px}
+ h1{font-size:20px;margin:0 0 4px} h2{font-size:14px;color:#8b929c;margin:18px 0 6px}
+ .card{background:#1b1f26;border:1px solid #2a2f39;border-radius:12px;padding:16px;margin:14px 0}
+ table{width:100%;border-collapse:collapse} td{padding:3px 0;font-size:14px}
+ td.v{text-align:right;font-weight:600} .muted{color:#8b929c}
+ .critical{color:#f87171} .warning{color:#fb923c} .ok{color:#4ade80} .info{color:#8b929c}
+ .badge{display:inline-block;background:#38bdf8;color:#06222e;border-radius:6px;padding:1px 8px;font-size:12px;font-weight:700}
+</style></head><body>
+ <h1>RigDoctor <span class="badge">read-only share</span></h1>
+ <p class="muted">A live view shared by the machine's owner. You can look, not change anything.</p>
+ <div class="card"><div id="live">loading…</div></div>
+ <div class="card"><h2 style="margin-top:0">Health</h2><div id="health">loading…</div></div>
+ <div class="card"><h2 style="margin-top:0">Inventory</h2><div id="inv">loading…</div></div>
+<script>
+ const T=new URLSearchParams(location.search).get('t');
+ const j=async p=>(await fetch(p+'?t='+encodeURIComponent(T))).json();
+ const fmt=(v,u)=>v==null?'N/A':(u==='\\u00b0C'?(+v).toFixed(1)+' °C':(u?v+' '+u:v));
+ async function live(){try{const d=await j('/api/snapshot');let h='';
+  for(const[g,items]of Object.entries(d.groups)){h+='<h2>'+g.toUpperCase()+'</h2><table>';
+   for(const it of items)h+='<tr><td class="muted">'+it.name+'</td><td class="v">'+fmt(it.value,it.unit)+'</td></tr>';
+   h+='</table>';}document.getElementById('live').innerHTML=h;}catch(e){}}
+ async function once(){try{const r=await j('/api/report');
+   document.getElementById('health').innerHTML=r.map(f=>'<div><span class="'+f.severity+'">['+f.severity.toUpperCase()+']</span> '+f.category+': '+f.title+'</div>').join('')||'no findings';}catch(e){}
+  try{const inv=await j('/api/inventory');let h='';
+   for(const[s,kv]of Object.entries(inv)){h+='<h2>'+s+'</h2><table>';
+    for(const[k,v]of Object.entries(kv))h+='<tr><td class="muted">'+k+'</td><td class="v">'+v+'</td></tr>';
+    h+='</table>';}document.getElementById('inv').innerHTML=h;}catch(e){}}
+ live();once();setInterval(live,2000);
+</script></body></html>"""
+
+
+def _snapshot(sampler: Sampler) -> dict:
+    sample = sampler.sample()
+    groups: dict[str, list] = {}
+    for r in sample.readings:
+        if r.metric == "name":
+            item = {"name": "device", "value": r.label, "unit": ""}
+        else:
+            item = {"name": (r.label + " " + r.metric).strip() if r.label else r.metric,
+                    "value": r.value, "unit": r.unit}
+        groups.setdefault(r.source, []).append(item)
+    return {"ts": sample.ts, "groups": groups}
+
+
+def _report() -> list:
+    from .health import run_health_checks
+    return [asdict(f) for f in run_health_checks()]
+
+
+def _inventory() -> dict:
+    from .inventory import collect, to_dict
+    return to_dict(collect())
+
+
+# --- Relay (M12) frames: a host streams these; a guest renders them. -----------------
+
+def host_full_frame(sampler: Sampler) -> str:
+    """Initial frame: live snapshot + health report + inventory."""
+    return json.dumps({"type": "full", "snapshot": _snapshot(sampler),
+                       "report": _report(), "inventory": _inventory()})
+
+
+def host_snapshot_frame(sampler: Sampler) -> str:
+    """Recurring frame: just the live snapshot."""
+    return json.dumps({"type": "snapshot", "snapshot": _snapshot(sampler)})
+
+
+def _fmt(value, unit: str) -> str:
+    if value is None:
+        return "N/A"
+    if unit == "°C":
+        try:
+            return f"{float(value):.1f} °C"
+        except (TypeError, ValueError):
+            return str(value)
+    return f"{value} {unit}".strip()
+
+
+def guest_html(snapshot: dict | None, report: list | None, inventory: dict | None) -> str:
+    """Render a received frame as read-only dark HTML for the guest's view."""
+    import html as _html
+
+    def esc(x) -> str:
+        return _html.escape(str(x))
+
+    out = ['<div style="font-family:sans-serif;color:#e6e8eb">']
+    if snapshot:
+        for group, items in snapshot.get("groups", {}).items():
+            out.append(f'<h3 style="color:#8b929c">{esc(group).upper()}</h3><table width="100%">')
+            for it in items:
+                out.append(f'<tr><td style="color:#8b929c">{esc(it.get("name"))}</td>'
+                           f'<td align="right"><b>{esc(_fmt(it.get("value"), it.get("unit", "")))}</b></td></tr>')
+            out.append("</table>")
+    if report:
+        out.append('<h3 style="color:#8b929c">HEALTH</h3>')
+        colors = {"critical": "#f87171", "warning": "#fb923c", "ok": "#4ade80"}
+        for f in report:
+            sev = f.get("severity", "info")
+            out.append(f'<div><span style="color:{colors.get(sev, "#8b929c")}">[{esc(sev).upper()}]</span> '
+                       f'{esc(f.get("category"))}: {esc(f.get("title"))}</div>')
+    if inventory:
+        out.append('<h3 style="color:#8b929c">INVENTORY</h3>')
+        for section, kv in inventory.items():
+            out.append(f'<h4 style="margin:6px 0;color:#8b929c">{esc(section)}</h4><table width="100%">')
+            for k, v in kv.items():
+                out.append(f'<tr><td style="color:#8b929c">{esc(k)}</td><td align="right"><b>{esc(v)}</b></td></tr>')
+            out.append("</table>")
+    out.append("</div>")
+    return "".join(out)
+
+
+class _Handler(BaseHTTPRequestHandler):
+    def log_message(self, *args):  # quiet
+        pass
+
+    def _authed(self, query: dict) -> bool:
+        return secrets.compare_digest(query.get("t", [""])[0], self.server.token)
+
+    def _send(self, code: int, ctype: str, body: bytes) -> None:
+        self.send_response(code)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self) -> None:  # noqa: N802
+        parsed = urlparse(self.path)
+        if not self._authed(parse_qs(parsed.query)):
+            self._send(403, "text/plain", b"Forbidden: missing or invalid share token")
+            return
+        if parsed.path == "/":
+            self._send(200, "text/html; charset=utf-8", _PAGE.encode())
+        elif parsed.path == "/api/snapshot":
+            self._send(200, "application/json", json.dumps(_snapshot(self.server.sampler)).encode())
+        elif parsed.path == "/api/report":
+            self._send(200, "application/json", json.dumps(_report()).encode())
+        elif parsed.path == "/api/inventory":
+            self._send(200, "application/json", json.dumps(_inventory()).encode())
+        else:
+            self._send(404, "text/plain", b"Not found")
+
+
+class _Server(ThreadingHTTPServer):
+    daemon_threads = True
+
+    def __init__(self, addr, token: str):
+        super().__init__(addr, _Handler)
+        self.token = token
+        self.sampler = Sampler(available_sources())
+
+
+def make_server(host: str = "127.0.0.1", port: int = 0, token: str | None = None) -> tuple[_Server, str]:
+    token = token or secrets.token_urlsafe(16)
+    return _Server((host, port), token), token
+
+
+def serve(host: str = "127.0.0.1", port: int = 8765) -> int:
+    srv, token = make_server(host, port)
+    url = f"http://{host}:{srv.server_address[1]}/?t={token}"
+    print(
+        f"Sharing a read-only live view at:\n  {url}\n\n"
+        "Anyone with this URL (and network access to this host) can VIEW your sensors,\n"
+        "health report, and inventory — read-only. For remote help, expose it via a tunnel\n"
+        "(Tailscale / cloudflared / `ssh -R`). Press Ctrl-C to stop sharing.",
+        flush=True,
+    )
+    try:
+        srv.serve_forever()
+    except KeyboardInterrupt:
+        print("\nStopped sharing.")
+    finally:
+        srv.shutdown()
+    return 0
@@ -0,0 +1,382 @@
+"""Steam library & game detection (M6, the Steam piece of D12 game detection).
+
+Discovers a user's Steam installs, the library folders they've configured (Steam tracks
+them all in ``libraryfolders.vdf``, so multiple libraries on multiple drives are covered),
+and the games installed in each (one ``appmanifest_<appid>.acf`` per app). Stdlib only —
+no Steam tooling required, every probe degrades gracefully.
+
+The set of libraries actually scanned is user-chosen (config ``steam_libraries``); nothing
+is scanned until the user opts a library in. Scan results are cached in ``games.json`` so the
+GUI can show the list instantly and the launch-time background scan can diff against it to
+flag newly-installed games.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from ..config import GAMES_FILE, load_config
+
+# Steam "apps" that aren't games: runtimes, Proton builds, redistributables. Filtered out of
+# scans by appid (known IDs) or by name prefix (covers future Proton/runtime versions).
+_TOOL_APPIDS = {
+    "228980",   # Steamworks Common Redistributables
+    "1070560",  # Steam Linux Runtime 1.0 (scout)
+    "1391110",  # Steam Linux Runtime 2.0 (soldier)
+    "1628350",  # Steam Linux Runtime 3.0 (sniper)
+    "1493710",  # Proton Experimental
+    "2180100",  # Proton Hotfix
+    "1826330",  # Proton EasyAntiCheat Runtime
+    "1161040",  # Proton BattlEye Runtime
+}
+_TOOL_NAME_PREFIXES = ("Proton", "Steam Linux Runtime", "Steamworks Common")
+
+# Where Steam may be installed (native + Flatpak + Snap). Symlinks (~/.steam/steam) are
+# resolved and de-duplicated by real path.
+_ROOT_CANDIDATES = (
+    "~/.steam/steam",
+    "~/.steam/root",
+    "~/.local/share/Steam",
+    "~/.var/app/com.valvesoftware.Steam/data/Steam",  # Flatpak
+    "~/snap/steam/common/.local/share/Steam",          # Snap
+)
+
+
+@dataclass
+class SteamLibrary:
+    path: str          # the library root (contains a steamapps/ dir)
+    label: str = ""    # Steam's label for the folder, if any
+
+
+@dataclass
+class Game:
+    appid: str
+    name: str
+    library: str       # library path the game lives in
+    installdir: str    # folder name under <library>/steamapps/common
+    size_bytes: int = 0
+    last_updated: int = 0  # epoch seconds (acf LastUpdated), 0 if unknown
+
+
+# --- VDF (Valve Data Format) parsing --------------------------------------------------
+# Minimal text-VDF reader: quoted "key" "value" pairs and "key" { ... } nesting. Enough
+# for libraryfolders.vdf and appmanifest_*.acf; ignores #base/#include and unquoted tokens.
+
+def _parse_vdf(text: str) -> dict:
+    pos = 0
+    n = len(text)
+
+    def skip_ws() -> None:
+        nonlocal pos
+        while pos < n:
+            c = text[pos]
+            if c in " \t\r\n":
+                pos += 1
+            elif c == "/" and pos + 1 < n and text[pos + 1] == "/":  # // line comment
+                while pos < n and text[pos] != "\n":
+                    pos += 1
+            else:
+                break
+
+    def read_string() -> str:
+        nonlocal pos
+        pos += 1  # opening quote
+        out = []
+        while pos < n:
+            c = text[pos]
+            if c == "\\" and pos + 1 < n:
+                nxt = text[pos + 1]
+                out.append({"n": "\n", "t": "\t", "\\": "\\", '"': '"'}.get(nxt, nxt))
+                pos += 2
+                continue
+            if c == '"':
+                pos += 1
+                break
+            out.append(c)
+            pos += 1
+        return "".join(out)
+
+    def parse_obj() -> dict:
+        nonlocal pos
+        obj: dict = {}
+        while True:
+            skip_ws()
+            if pos >= n or text[pos] == "}":
+                pos += 1  # consume closing brace (or run off the end)
+                return obj
+            if text[pos] != '"':  # skip unquoted/unsupported tokens defensively
+                pos += 1
+                continue
+            key = read_string()
+            skip_ws()
+            if pos < n and text[pos] == "{":
+                pos += 1
+                obj[key] = parse_obj()
+            elif pos < n and text[pos] == '"':
+                obj[key] = read_string()
+            else:  # malformed; bail on this key
+                obj[key] = ""
+        return obj
+
+    skip_ws()
+    if pos < n and text[pos] == '"':
+        root_key = read_string()
+        skip_ws()
+        if pos < n and text[pos] == "{":
+            pos += 1
+            return {root_key: parse_obj()}
+    return {}
+
+
+def _read_vdf(path: Path) -> dict:
+    try:
+        return _parse_vdf(path.read_text(encoding="utf-8", errors="replace"))
+    except OSError:
+        return {}
+
+
+# --- discovery ------------------------------------------------------------------------
+
+def steam_roots() -> list[Path]:
+    """Existing Steam install roots, de-duplicated by resolved path."""
+    seen: set[Path] = set()
+    roots: list[Path] = []
+    for cand in _ROOT_CANDIDATES:
+        p = Path(os.path.expanduser(cand))
+        if not p.exists():
+            continue
+        real = p.resolve()
+        if real in seen:
+            continue
+        seen.add(real)
+        roots.append(real)
+    return roots
+
+
+def _libraryfolders_vdf(root: Path) -> Path | None:
+    for rel in ("steamapps/libraryfolders.vdf", "config/libraryfolders.vdf"):
+        p = root / rel
+        if p.exists():
+            return p
+    return None
+
+
+def discover_libraries() -> list[SteamLibrary]:
+    """Every Steam library folder configured on this machine, de-duplicated by real path.
+
+    Reads each install's ``libraryfolders.vdf`` (which lists all drives/folders), and
+    always includes the install root itself as a fallback.
+    """
+    seen: set[Path] = set()
+    libs: list[SteamLibrary] = []
+
+    def add(path: Path, label: str = "") -> None:
+        if not (path / "steamapps").is_dir():
+            return
+        real = path.resolve()
+        if real in seen:
+            return
+        seen.add(real)
+        libs.append(SteamLibrary(path=str(real), label=label))
+
+    for root in steam_roots():
+        vdf = _libraryfolders_vdf(root)
+        folders = _read_vdf(vdf).get("libraryfolders", {}) if vdf else {}
+        if isinstance(folders, dict):
+            for entry in folders.values():
+                if isinstance(entry, dict) and entry.get("path"):
+                    add(Path(entry["path"]), entry.get("label", ""))
+        add(root)  # the install root is itself a library
+    return libs
+
+
+# --- game scanning --------------------------------------------------------------------
+
+def is_tool(appid: str, name: str) -> bool:
+    """True for non-game Steam apps (runtimes, Proton, redistributables)."""
+    if appid in _TOOL_APPIDS:
+        return True
+    return name.startswith(_TOOL_NAME_PREFIXES)
+
+
+def scan_library(library: str) -> list[Game]:
+    """Games installed in one library, parsed from its appmanifest_*.acf files."""
+    steamapps = Path(library) / "steamapps"
+    games: list[Game] = []
+    try:
+        manifests = sorted(steamapps.glob("appmanifest_*.acf"))
+    except OSError:
+        return games
+    for manifest in manifests:
+        state = _read_vdf(manifest).get("AppState", {})
+        if not isinstance(state, dict):
+            continue
+        # Steam treats VDF keys case-insensitively (e.g. "SizeOnDisk" but "lastupdated").
+        state = {k.lower(): v for k, v in state.items()}
+        appid = state.get("appid", "")
+        name = state.get("name", "").strip()
+        if not appid or not name or is_tool(appid, name):
+            continue
+        games.append(Game(
+            appid=appid,
+            name=name,
+            library=str(library),
+            installdir=state.get("installdir", ""),
+            size_bytes=_int(state.get("sizeondisk")),
+            last_updated=_int(state.get("lastupdated")),
+        ))
+    return games
+
+
+def scan_games(libraries: list[str]) -> list[Game]:
+    """All games across the given libraries, de-duplicated by appid, sorted by name."""
+    by_appid: dict[str, Game] = {}
+    for lib in libraries:
+        for game in scan_library(lib):
+            by_appid.setdefault(game.appid, game)  # first library wins on duplicates
+    return sorted(by_appid.values(), key=lambda g: g.name.lower())
+
+
+def _int(value) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return 0
+
+
+def proton_versions() -> list[str]:
+    """Installed Proton compatibility-tool versions across all discovered libraries.
+
+    Proton builds are the appmanifests we filter out of game scans; here we surface them
+    for the M6 environment report. Returns unique names, newest-looking last.
+    """
+    names: set[str] = set()
+    for lib in discover_libraries():
+        try:
+            manifests = sorted((Path(lib.path) / "steamapps").glob("appmanifest_*.acf"))
+        except OSError:
+            continue
+        for manifest in manifests:
+            state = _read_vdf(manifest).get("AppState", {})
+            if isinstance(state, dict):
+                state = {k.lower(): v for k, v in state.items()}
+                name = state.get("name", "").strip()
+                if name.startswith("Proton"):
+                    names.add(name)
+    return sorted(names)
+
+
+# --- config-driven selection ----------------------------------------------------------
+
+def selected_library_paths(cfg: dict | None = None) -> list[str]:
+    """Library paths the user has opted in to scanning (config ``steam_libraries``)."""
+    cfg = cfg or load_config()
+    paths = cfg.get("steam_libraries") or []
+    return [str(p) for p in paths]
+
+
+# --- scan cache + new-game detection --------------------------------------------------
+
+@dataclass
+class ScanResult:
+    games: list[Game]
+    new_appids: list[str]   # newly-installed since the last scan (badge fuel)
+    scanned_at: float
+
+
+def load_cache() -> dict | None:
+    try:
+        return json.loads(GAMES_FILE.read_text())
+    except (OSError, ValueError):
+        return None
+
+
+def _save_cache(games: list[Game], known: set[str], new: list[str], when: float) -> None:
+    GAMES_FILE.parent.mkdir(parents=True, exist_ok=True)
+    data = {
+        "scanned_at": when,
+        "known_appids": sorted(known),
+        "new_appids": new,
+        "games": [asdict(g) for g in games],
+    }
+    GAMES_FILE.write_text(json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def cached_games() -> list[Game]:
+    """Games from the last scan (for instant display before a rescan finishes)."""
+    cache = load_cache()
+    if not cache:
+        return []
+    return [Game(**{k: g.get(k) for k in Game.__dataclass_fields__}) for g in cache.get("games", [])]
+
+
+def rescan(cfg: dict | None = None) -> ScanResult:
+    """Scan the selected libraries, diff against the cache, and persist the result.
+
+    Newly-installed games (appids never seen before) are reported in ``new_appids``. The
+    very first scan reports nothing as new (so the whole library isn't flagged at once);
+    unacknowledged new games carry forward until they're acknowledged or uninstalled.
+    """
+    games = scan_games(selected_library_paths(cfg))
+    current = {g.appid for g in games}
+    prev = load_cache()
+    if prev is None:
+        known: set[str] = set(current)  # first run: everything is "known", nothing new
+        new = []
+    else:
+        known = set(prev.get("known_appids", []))
+        carried = set(prev.get("new_appids", [])) & current  # still-unacknowledged & installed
+        new = sorted((current - known) | carried)
+        known |= current
+    when = time.time()
+    _save_cache(games, known, new, when)
+    return ScanResult(games=games, new_appids=new, scanned_at=when)
+
+
+def acknowledge_new() -> None:
+    """Clear the new-game badge (called when the user views the games list)."""
+    cache = load_cache()
+    if not cache or not cache.get("new_appids"):
+        return
+    cache["new_appids"] = []
+    try:
+        GAMES_FILE.write_text(json.dumps(cache, indent=2, ensure_ascii=False))
+    except OSError:
+        pass
+
+
+# --- formatting -----------------------------------------------------------------------
+
+def launch_game(appid: str) -> bool:
+    """Best-effort: ask Steam to launch a game by appid (steam:// URL). Non-blocking."""
+    if not appid:
+        return False
+    url = f"steam://rungameid/{appid}"
+    for cmd in (["steam", url], ["xdg-open", url]):
+        if shutil.which(cmd[0]):
+            try:
+                subprocess.Popen(
+                    cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                    stdin=subprocess.DEVNULL, start_new_session=True,
+                )
+                return True
+            except (OSError, subprocess.SubprocessError):
+                continue
+    return False
+
+
+def human_size(num_bytes: int) -> str:
+    if num_bytes <= 0:
+        return "—"
+    size = float(num_bytes)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if size < 1024 or unit == "TB":
+            return f"{size:.0f} {unit}" if unit in ("B", "KB") else f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{size:.1f} TB"
@@ -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
@@ -0,0 +1,42 @@
+"""Uninstall the user-local RigDoctor install (app files; optionally all data).
+
+Mirrors `install.sh --uninstall`. The removal runs in a detached shell so it can
+delete the venv the current process is running from once we exit.
+"""
+
+from __future__ import annotations
+
+import shlex
+import subprocess
+from pathlib import Path
+
+from .. import config
+from . import reccontrol
+
+
+def targets(purge: bool = False) -> list[Path]:
+    """Paths removed by an uninstall. With purge, also config/state/logs."""
+    home = Path.home()
+    share = config.DATA_DIR.parent  # ~/.local/share
+    items = [
+        config.DATA_DIR / "venv",
+        home / ".local" / "bin" / "rigdoctor",
+        home / ".local" / "bin" / "rigdoctor-gui",
+        share / "applications" / "rigdoctor.desktop",
+        share / "icons" / "hicolor" / "scalable" / "apps" / "rigdoctor.svg",
+    ]
+    if purge:
+        items += [config.CONFIG_DIR, config.STATE_DIR, config.DATA_DIR]
+    return items
+
+
+def uninstall(purge: bool = False) -> None:
+    """Stop the recorder, clear the token if purging, and remove the install."""
+    reccontrol.stop_background()
+    if purge:
+        config.clear_token()  # removes keyring entry + any file fallback
+    paths = " ".join(shlex.quote(str(p)) for p in targets(purge))
+    subprocess.Popen(
+        ["/bin/sh", "-c", f"sleep 1; rm -rf {paths}"],
+        start_new_session=True,
+    )
@@ -0,0 +1,119 @@
+"""Update check (M13): ask the Gitea releases API for the latest version + notes.
+
+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`. Returns the latest tag, its release notes (body), and a clear
+state for the UI; `apply_update` performs the no-root self-update.
+"""
+
+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, str | None]:
+    """Return (tag, notes, error). error is 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, (data.get("body") or "").strip(), 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 notes/error)."""
+    tag, _notes, _error = fetch_latest(timeout)
+    return tag
+
+
+def update_state(timeout: float = 5.0) -> tuple[str, str | None, str]:
+    """Return (state, tag, notes). state in NO_TOKEN/AUTH/NETWORK/UP_TO_DATE/AVAILABLE."""
+    tag, notes, error = fetch_latest(timeout)
+    if error:
+        return (error, None, "")
+    if tag and is_newer(tag):
+        return (AVAILABLE, tag, notes)
+    return (UP_TO_DATE, tag, notes)
+
+
+def list_releases(limit: int = 15, timeout: float = 6.0) -> tuple[list[tuple[str, str, str]], str | None]:
+    """Return ([(tag, date, notes), …], error) for the in-app changelog."""
+    token = load_token()
+    if not token:
+        return ([], NO_TOKEN)
+    req = urllib.request.Request(
+        f"{GITEA_BASE}/api/v1/repos/{REPO}/releases?limit={limit}",
+        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 ([
+            (r.get("tag_name") or "?", (r.get("published_at") or "")[:10], (r.get("body") or "").strip())
+            for r in data
+        ], None)
+    except urllib.error.HTTPError as exc:
+        return ([], AUTH if exc.code in (401, 403) else NETWORK)
+    except Exception:
+        return ([], NETWORK)
+
+
+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, "***"))
@@ -3,18 +3,28 @@
 from __future__ import annotations

 import sys
+from pathlib import Path

+from PySide6.QtGui import QIcon
 from PySide6.QtWidgets import QApplication

 from ..config import load_config
+from . import desktop
 from .main_window import MainWindow
 from .theme import STYLESHEET

+ICON = Path(__file__).parent / "assets" / "rigdoctor.svg"
+

 def main(argv: list[str] | None = None) -> int:
+    desktop.ensure()  # self-register icon + .desktop so updates show it without re-installing
    app = QApplication(argv if argv is not None else sys.argv)
    app.setApplicationName("RigDoctor")
    app.setApplicationDisplayName("RigDoctor")
+    # Match the installed rigdoctor.desktop so the dock/launcher shows our icon (Wayland app-id).
+    app.setDesktopFileName("rigdoctor")
+    if ICON.exists():
+        app.setWindowIcon(QIcon(str(ICON)))
    app.setStyle("Fusion")
    app.setStyleSheet(STYLESHEET)

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16">
+  <path d="M3.5 8.5 L6.5 11.5 L12.5 4.5" fill="none" stroke="#06222e"
+        stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256">
+  <rect x="8" y="8" width="240" height="240" rx="52" fill="#15181e"/>
+  <circle cx="128" cy="128" r="84" fill="none" stroke="#2a2f39" stroke-width="14"/>
+  <path d="M128 44 a84 84 0 1 1 -59.4 24.6" fill="none" stroke="#38bdf8"
+        stroke-width="14" stroke-linecap="round"/>
+  <path d="M60 132 H100 L116 96 L140 168 L156 132 H196" fill="none" stroke="#e6e8eb"
+        stroke-width="14" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
@@ -17,19 +17,19 @@ from PySide6.QtWidgets import (

 from ..core.sample import Sample
 from ..render import metric_label
-from .widgets import Card, MetricBar, MetricRow, StatGauge
+from .widgets import Card, HistoryGraph, MetricBar, MetricRow

 _GROUP_ORDER = ["gpu", "cpu", "memory", "storage"]
 _GROUP_TITLES = {"gpu": "GPU", "cpu": "CPU", "memory": "Memory", "storage": "Storage"}
 _BAR_METRICS = {"util", "mem_util", "fan", "used_pct"}


-def _gauge_card(gauge: StatGauge) -> QFrame:
+def _tile_card(widget: QWidget) -> QFrame:
    card = QFrame()
    card.setObjectName("Card")
    layout = QVBoxLayout(card)
-    layout.setContentsMargins(6, 14, 6, 8)
-    layout.addWidget(gauge)
+    layout.setContentsMargins(6, 10, 6, 8)
+    layout.addWidget(widget)
    return card


@@ -54,16 +54,16 @@ class Dashboard(QWidget):
        header.addWidget(self._updated)
        root.addLayout(header)

-        # Headline gauges
-        self._g_gpu_temp = StatGauge("GPU Temp", "°C", 100, "temp")
-        self._g_gpu_load = StatGauge("GPU Load", "%", 100, "accent")
-        self._g_cpu_temp = StatGauge("CPU Temp", "°C", 100, "temp")
-        self._g_mem = StatGauge("Memory", "%", 100, "usage")
-        gauges = QHBoxLayout()
-        gauges.setSpacing(14)
+        # Headline trend graphs (history over the session, not just the live value)
+        self._g_gpu_temp = HistoryGraph("GPU Temp", "°C", 30, 100, "temp")
+        self._g_gpu_load = HistoryGraph("GPU Load", "%", 0, 100, "accent")
+        self._g_cpu_temp = HistoryGraph("CPU Temp", "°C", 30, 100, "temp")
+        self._g_mem = HistoryGraph("Memory", "%", 0, 100, "usage")
+        graphs = QHBoxLayout()
+        graphs.setSpacing(14)
        for g in (self._g_gpu_temp, self._g_gpu_load, self._g_cpu_temp, self._g_mem):
-            gauges.addWidget(_gauge_card(g))
-        root.addLayout(gauges)
+            graphs.addWidget(_tile_card(g))
+        root.addLayout(graphs)

        # Per-subsystem cards (scrollable, 2-column grid)
        scroll = QScrollArea()
@@ -81,10 +81,10 @@ class Dashboard(QWidget):
        root.addWidget(scroll, 1)

    def update_sample(self, sample: Sample) -> None:
-        self._g_gpu_temp.set_value(self._val(sample, "gpu", "temp", ""))
-        self._g_gpu_load.set_value(self._val(sample, "gpu", "util"))
-        self._g_cpu_temp.set_value(self._cpu_temp(sample))
-        self._g_mem.set_value(self._val(sample, "memory", "used_pct"))
+        self._g_gpu_temp.add_value(self._val(sample, "gpu", "temp", ""))
+        self._g_gpu_load.add_value(self._val(sample, "gpu", "util"))
+        self._g_cpu_temp.add_value(self._cpu_temp(sample))
+        self._g_mem.add_value(self._val(sample, "memory", "used_pct"))

        keys = [r.key for r in sample.readings]
        if keys != self._built_keys:  # sources appeared/disappeared
@@ -0,0 +1,51 @@
+"""Best-effort desktop integration: install our icon + .desktop so the dock shows it.
+
+Runs at GUI launch (idempotent), so a self-update + relaunch refreshes the icon without
+re-running install.sh. No-op for non-installed (dev) runs where the launcher is absent.
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+from .. import config
+
+_ICON_SRC = Path(__file__).parent / "assets" / "rigdoctor.svg"
+
+_DESKTOP = """[Desktop Entry]
+Type=Application
+Name=RigDoctor
+Comment=Hardware monitoring & crash diagnostics for Linux gamers
+Exec={exec}
+Icon=rigdoctor
+Terminal=false
+Categories=System;Monitor;Utility;
+StartupWMClass=rigdoctor
+"""
+
+
+def ensure() -> None:
+    share = config.DATA_DIR.parent  # ~/.local/share
+
+    try:
+        if _ICON_SRC.exists():
+            icon_dst = share / "icons" / "hicolor" / "scalable" / "apps" / "rigdoctor.svg"
+            icon_dst.parent.mkdir(parents=True, exist_ok=True)
+            if not icon_dst.exists() or icon_dst.read_bytes() != _ICON_SRC.read_bytes():
+                shutil.copyfile(_ICON_SRC, icon_dst)
+    except OSError:
+        pass
+
+    gui_exec = Path(sys.executable).with_name("rigdoctor-gui")
+    if not gui_exec.exists():  # dev / not a normal install — don't fabricate a .desktop
+        return
+    try:
+        desktop = share / "applications" / "rigdoctor.desktop"
+        content = _DESKTOP.format(exec=gui_exec)
+        desktop.parent.mkdir(parents=True, exist_ok=True)
+        if not desktop.exists() or desktop.read_text() != content:
+            desktop.write_text(content)
+    except OSError:
+        pass
@@ -0,0 +1,81 @@
+"""Results view for a guided diagnostic session (M6/D12): capture summary + findings."""
+
+from __future__ import annotations
+
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QFont
+from PySide6.QtWidgets import (
+    QDialog,
+    QFrame,
+    QHBoxLayout,
+    QLabel,
+    QPushButton,
+    QScrollArea,
+    QVBoxLayout,
+    QWidget,
+)
+
+from ..render import render_summary
+from .widgets import finding_card
+
+
+class DiagnosticDialog(QDialog):
+    def __init__(self, result, parent=None) -> None:
+        super().__init__(parent)
+        self.setWindowTitle(f"Diagnostic — {result.game}" if result.game else "Diagnostic")
+        self.resize(660, 680)
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(20, 18, 20, 16)
+        root.setSpacing(14)
+
+        title = QLabel(f"Diagnostic — {result.game}" if result.game else "Diagnostic")
+        title.setObjectName("PageTitle")
+        root.addWidget(title)
+
+        scroll = QScrollArea()
+        scroll.setWidgetResizable(True)
+        scroll.setFrameShape(QFrame.Shape.NoFrame)
+        scroll.setStyleSheet("background: transparent;")
+        body = QWidget()
+        col = QVBoxLayout(body)
+        col.setContentsMargins(0, 0, 0, 0)
+        col.setSpacing(10)
+        col.setAlignment(Qt.AlignmentFlag.AlignTop)
+
+        # Capture window summary (peaks / events / last samples) — monospace for the columns.
+        cap_head = QLabel("Capture")
+        cap_head.setStyleSheet("font-weight: 700; background: transparent;")
+        col.addWidget(cap_head)
+        summary = QLabel(render_summary(result.summary))
+        summary.setObjectName("Report")
+        summary.setFont(QFont("monospace"))
+        summary.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+        summary.setWordWrap(False)
+        summary.setStyleSheet(
+            "background: #0d0f13; color: #cfd3da; border: 1px solid #2a2f39; "
+            "border-radius: 8px; padding: 10px;"
+        )
+        col.addWidget(summary)
+
+        find_head = QLabel(f"Findings ({len(result.findings)})")
+        find_head.setStyleSheet("font-weight: 700; background: transparent;")
+        col.addWidget(find_head)
+        if result.findings:
+            for finding in result.findings:
+                col.addWidget(finding_card(finding))
+        else:
+            none = QLabel("No findings.")
+            none.setObjectName("Muted")
+            col.addWidget(none)
+
+        scroll.setWidget(body)
+        root.addWidget(scroll, 1)
+
+        buttons = QHBoxLayout()
+        buttons.addStretch(1)
+        close = QPushButton("Close")
+        close.setObjectName("PrimaryButton")
+        close.clicked.connect(self.accept)
+        buttons.addWidget(close)
+        root.addLayout(buttons)
@@ -0,0 +1,156 @@
+"""Environment page (M6 in the GUI): runs the gaming-environment checks as findings 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 .widgets import finding_card
+
+
+def _fail_reason(out: str) -> str:
+    """Turn the failed command's output into a short, human reason."""
+    low = (out or "").lower()
+    if "not authorized" in low or "dismissed" in low or "authentication" in low:
+        return "cancelled at the password prompt"
+    if "operation not permitted" in low or "invalid argument" in low or "permission denied" in low:
+        return "the system rejected the change (it may be locked by BIOS/kernel)"
+    last = next((ln.strip() for ln in reversed((out or "").splitlines()) if ln.strip()), "")
+    return (last[:80] or "no privileges, or cancelled")
+
+
+class EnvironmentPage(QWidget):
+    _result = Signal(object)       # list[Finding]
+    _action_done = Signal(object)  # (label, rc, output) — install or apply finished
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.setObjectName("Page")
+        self._result.connect(self._render_findings)
+        self._action_done.connect(self._on_action_done)
+        self._busy = False
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(20, 18, 20, 18)
+        root.setSpacing(16)
+
+        header = QHBoxLayout()
+        title = QLabel("Environment")
+        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 checks")
+        self._run_btn.setObjectName("PrimaryButton")
+        self._run_btn.clicked.connect(self._run)
+        header.addWidget(self._run_btn)
+        root.addLayout(header)
+
+        intro = QLabel(
+            "System settings that affect gaming stability and performance, with the suggested "
+            "fix command. RigDoctor only reports — it never changes anything."
+        )
+        intro.setObjectName("Muted")
+        intro.setWordWrap(True)
+        root.addWidget(intro)
+
+        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(350, self._run)  # auto-run shortly after the window opens
+
+    def _run(self) -> None:
+        self._run_btn.setEnabled(False)
+        self._status.setText("Checking environment…")
+        threading.Thread(target=self._work, daemon=True).start()
+
+    def _work(self) -> None:
+        from ..core.gameenv import run_gameenv_checks
+
+        try:
+            findings = run_gameenv_checks()
+        except Exception:
+            findings = None
+        self._result.emit(findings)
+
+    def _render_findings(self, findings) -> None:
+        self._run_btn.setEnabled(True)
+        if findings is None:  # check failed — keep current results
+            self._status.setText("check failed")
+            return
+
+        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_card(finding, on_install=self._install, on_apply=self._apply))
+        self._list.addStretch(1)
+
+    def _install(self, component) -> None:
+        if self._busy:
+            return
+        self._busy = True
+        self._run_btn.setEnabled(False)
+        self._status.setText(f"Installing {component.name}… (may prompt for your password)")
+        threading.Thread(target=self._work_install, args=(component,), daemon=True).start()
+
+    def _work_install(self, component) -> None:
+        from ..core import installer
+
+        rc, out = installer.install_packages(list(component.apt))
+        self._action_done.emit((component.name, rc, out))
+
+    def _apply(self, fix_id: str, value: str) -> None:
+        if self._busy:
+            return
+        self._busy = True
+        self._run_btn.setEnabled(False)
+        self._status.setText(f"Applying {value}… (may prompt for your password)")
+        threading.Thread(target=self._work_apply, args=(fix_id, value), daemon=True).start()
+
+    def _work_apply(self, fix_id: str, value: str) -> None:
+        from ..core import fixes
+
+        rc, out = fixes.apply(fix_id, value)
+        self._action_done.emit((value, rc, out))
+
+    def _on_action_done(self, result) -> None:
+        label, rc, out = result
+        self._busy = False
+        if rc == 0:
+            self._status.setText(f"{label} applied — re-checking…")
+            self._run()  # re-run so the finding reflects the new state
+        else:
+            self._run_btn.setEnabled(True)
+            self._status.setText(f"'{label}' failed — {_fail_reason(out)}")
@@ -0,0 +1,394 @@
+"""Games page (M6 in the GUI): pick Steam libraries and browse detected games.
+
+Libraries are opt-in — the user checks which ones to scan. The list is loaded from the
+cache instantly, then a background rescan refreshes it and flags games installed since the
+last scan (a "NEW" badge here + a count on the sidebar nav).
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+
+from PySide6.QtCore import Qt, QTimer, Signal
+from PySide6.QtWidgets import (
+    QCheckBox,
+    QFrame,
+    QHBoxLayout,
+    QLabel,
+    QMessageBox,
+    QPushButton,
+    QScrollArea,
+    QVBoxLayout,
+    QWidget,
+)
+
+from ..config import load_config, update_config
+from .diagnostic_dialog import DiagnosticDialog
+from .theme import ACCENT, GOOD, MUTED
+
+
+def _game_row(name: str, sublabel: str, size: str, is_new: bool, appid: str = "", on_diagnose=None) -> QFrame:
+    card = QFrame()
+    card.setObjectName("Card")
+    h = QHBoxLayout(card)
+    h.setContentsMargins(16, 10, 16, 10)
+    h.setSpacing(10)
+
+    left = QVBoxLayout()
+    left.setSpacing(2)
+    title = QLabel(name)
+    title.setStyleSheet("font-weight: 600; background: transparent;")
+    title.setWordWrap(True)
+    left.addWidget(title)
+    if sublabel:
+        sub = QLabel(sublabel)
+        sub.setObjectName("Muted")
+        left.addWidget(sub)
+    h.addLayout(left, 1)
+
+    if is_new:
+        badge = QLabel("NEW")
+        badge.setStyleSheet(
+            f"color: {GOOD}; border: 1px solid {GOOD}; border-radius: 6px; "
+            f"padding: 1px 6px; font-weight: 700; background: transparent;"
+        )
+        h.addWidget(badge, 0, Qt.AlignmentFlag.AlignVCenter)
+
+    size_label = QLabel(size)
+    size_label.setObjectName("Muted")
+    size_label.setMinimumWidth(80)
+    size_label.setAlignment(Qt.AlignmentFlag.AlignRight | Qt.AlignmentFlag.AlignVCenter)
+    h.addWidget(size_label, 0)
+
+    if on_diagnose is not None:
+        diag_btn = QPushButton("Run Diagnostic")
+        diag_btn.setObjectName("ActionButton")
+        diag_btn.setCursor(Qt.CursorShape.PointingHandCursor)
+        diag_btn.clicked.connect(lambda: on_diagnose(name, appid))
+        h.addWidget(diag_btn, 0)
+    return card
+
+
+class GamesPage(QWidget):
+    _libraries_ready = Signal(object)  # list[dict(path, label, count, selected)]
+    _scanned = Signal(object)          # steam.ScanResult
+    new_count_changed = Signal(int)    # newly-installed game count (for the nav badge)
+    _diag_done = Signal(object)        # DiagnosticResult — focused capture analyzed
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.setObjectName("Page")
+        self._libraries_ready.connect(self._render_libraries)
+        self._scanned.connect(self._render_games)
+        self._diag_done.connect(self._on_diag_done)
+        self._busy = False
+        self._new_appids: set[str] = set()
+        self._diag_game: str | None = None
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(20, 18, 20, 18)
+        root.setSpacing(16)
+
+        header = QHBoxLayout()
+        title = QLabel("Games")
+        title.setObjectName("PageTitle")
+        header.addWidget(title)
+        header.addStretch(1)
+        self._status = QLabel("")
+        self._status.setObjectName("Muted")
+        header.addWidget(self._status)
+        self._rescan_btn = QPushButton("Rescan")
+        self._rescan_btn.setObjectName("PrimaryButton")
+        self._rescan_btn.clicked.connect(self.refresh)
+        header.addWidget(self._rescan_btn)
+        root.addLayout(header)
+
+        # In-progress diagnostic banner (hidden until a focused capture is running).
+        self._banner = QFrame()
+        self._banner.setObjectName("Card")
+        self._banner.setStyleSheet(f"#Card {{ border: 1px solid {ACCENT}; }}")
+        banner_h = QHBoxLayout(self._banner)
+        banner_h.setContentsMargins(16, 10, 16, 10)
+        banner_h.setSpacing(10)
+        self._banner_label = QLabel("")
+        self._banner_label.setWordWrap(True)
+        self._banner_label.setStyleSheet(f"color: {ACCENT}; font-weight: 700; background: transparent;")
+        banner_h.addWidget(self._banner_label, 1)
+        self._finish_btn = QPushButton("Finish && analyze")  # && → literal & (not a mnemonic)
+        self._finish_btn.setObjectName("ActionButton")
+        self._finish_btn.clicked.connect(self._finish_diagnostic)
+        banner_h.addWidget(self._finish_btn)
+        self._discard_btn = QPushButton("Discard")
+        self._discard_btn.clicked.connect(self._discard_diagnostic)
+        banner_h.addWidget(self._discard_btn)
+        self._banner.hide()
+        root.addWidget(self._banner)
+
+        self._diag_timer = QTimer(self)
+        self._diag_timer.setInterval(1000)
+        self._diag_timer.timeout.connect(self._poll_diag)
+
+        # Libraries (opt-in checkboxes)
+        lib_card = QFrame()
+        lib_card.setObjectName("Card")
+        lib_v = QVBoxLayout(lib_card)
+        lib_v.setContentsMargins(16, 12, 16, 12)
+        lib_v.setSpacing(6)
+        lib_head = QLabel("Steam libraries")
+        lib_head.setStyleSheet("font-weight: 700; background: transparent;")
+        lib_v.addWidget(lib_head)
+        self._lib_box = QVBoxLayout()
+        self._lib_box.setSpacing(6)
+        lib_v.addLayout(self._lib_box)
+        self._lib_hint = QLabel("Looking for Steam libraries…")
+        self._lib_hint.setObjectName("Muted")
+        self._lib_hint.setWordWrap(True)
+        lib_v.addWidget(self._lib_hint)
+        root.addWidget(lib_card)
+
+        # Games list
+        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(8)
+        self._list.setAlignment(Qt.AlignmentFlag.AlignTop)
+        scroll.setWidget(self._container)
+        root.addWidget(scroll, 1)
+
+        self._load_cached()                       # instant display from the last scan
+        QTimer.singleShot(400, self.refresh)      # then rescan in the background on launch
+
+    # --- loading ----------------------------------------------------------------------
+
+    def _load_cached(self) -> None:
+        from ..core import steam
+
+        cache = steam.load_cache() or {}
+        self._new_appids = set(cache.get("new_appids", []))
+        games = steam.cached_games()
+        if games:
+            self._populate_games(games, self._new_appids)
+        self.new_count_changed.emit(len(self._new_appids))
+
+    def refresh(self) -> None:
+        if self._busy:
+            return
+        self._busy = True
+        self._rescan_btn.setEnabled(False)
+        self._status.setText("Scanning Steam libraries…")
+        threading.Thread(target=self._work, daemon=True).start()
+
+    def _work(self) -> None:
+        from ..core import steam
+
+        try:
+            selected = {os.path.realpath(p) for p in steam.selected_library_paths()}
+            libs = [
+                {"path": lib.path, "label": lib.label, "selected": lib.path in selected,
+                 "count": len(steam.scan_library(lib.path))}
+                for lib in steam.discover_libraries()
+            ]
+            self._libraries_ready.emit(libs)
+            self._scanned.emit(steam.rescan())
+        except Exception:
+            self._scanned.emit(None)
+
+    # --- rendering --------------------------------------------------------------------
+
+    def _render_libraries(self, libs) -> None:
+        while self._lib_box.count():
+            item = self._lib_box.takeAt(0)
+            w = item.widget()
+            if w is not None:
+                w.deleteLater()
+        if not libs:
+            self._lib_hint.setText("No Steam libraries detected. Is Steam installed?")
+            self._lib_hint.show()
+            return
+        self._lib_hint.hide()
+        for lib in libs:
+            label = lib["path"]
+            if lib["label"]:
+                label += f"  [{lib['label']}]"
+            cb = QCheckBox(f"{label}    ·  {lib['count']} games")
+            cb.setChecked(lib["selected"])
+            cb.toggled.connect(lambda checked, p=lib["path"]: self._toggle_library(p, checked))
+            self._lib_box.addWidget(cb)
+
+    def _toggle_library(self, path: str, checked: bool) -> None:
+        selected = {os.path.realpath(p) for p in (load_config().get("steam_libraries") or [])}
+        if checked:
+            selected.add(os.path.realpath(path))
+        else:
+            selected.discard(os.path.realpath(path))
+        update_config(steam_libraries=sorted(selected))
+        self.refresh()
+
+    def _render_games(self, result) -> None:
+        self._busy = False
+        self._rescan_btn.setEnabled(True)
+        if result is None:
+            self._status.setText("scan failed")
+            return
+        self._new_appids = set(result.new_appids)
+        self._populate_games(result.games, self._new_appids)
+        new = len(self._new_appids)
+        suffix = f"  ·  {new} new" if new else ""
+        self._status.setText(
+            f"{len(result.games)} games  ·  {time.strftime('%H:%M:%S')}{suffix}"
+        )
+        self.new_count_changed.emit(new)
+
+    def _populate_games(self, games, new_appids: set[str]) -> None:
+        from ..core import steam
+
+        while self._list.count():
+            item = self._list.takeAt(0)
+            w = item.widget()
+            if w is not None:
+                w.deleteLater()
+
+        if not games:
+            empty = QLabel(
+                "No games to show yet — check a Steam library above to scan it for games."
+            )
+            empty.setObjectName("Muted")
+            empty.setWordWrap(True)
+            self._list.addWidget(empty)
+            self._list.addStretch(1)
+            return
+
+        for g in games:
+            self._list.addWidget(_game_row(
+                g.name,
+                os.path.basename(g.library.rstrip("/")) or g.library,
+                steam.human_size(g.size_bytes),
+                g.appid in new_appids,
+                appid=g.appid,
+                on_diagnose=self._start_diagnostic,
+            ))
+        self._list.addStretch(1)
+
+    # --- guided diagnostic (M6/D12) ---------------------------------------------------
+
+    def _start_diagnostic(self, name: str, appid: str = "") -> None:
+        from ..core import diagnostic, steam
+
+        if diagnostic.is_running():
+            QMessageBox.information(
+                self, "RigDoctor",
+                "A capture is already running — finish or discard it first.")
+            return
+
+        # Tell the user what the flow actually is, and offer to launch the game for them.
+        box = QMessageBox(self)
+        box.setIcon(QMessageBox.Icon.Information)
+        box.setWindowTitle(f"Run Diagnostic — {name}")
+        box.setText(f"Record a focused diagnostic while you play {name}?")
+        box.setInformativeText(
+            "RigDoctor will capture sensors in the background. Then:\n\n"
+            "1.  Play the game and try to reproduce the freeze / black screen / crash.\n"
+            "2.  When you're done — or after a hard freeze and reboot — come back here and "
+            "click “Finish & analyze”.\n\n"
+            "Your readings are saved continuously, so even a hard lock won't lose them."
+        )
+        launch_btn = box.addButton("Launch game && start", QMessageBox.ButtonRole.AcceptRole)
+        start_btn = box.addButton("Start without launching", QMessageBox.ButtonRole.ActionRole)
+        box.addButton("Cancel", QMessageBox.ButtonRole.RejectRole)
+        if not appid:
+            launch_btn.setEnabled(False)  # no appid → can't ask Steam to launch it
+        box.exec()
+        clicked = box.clickedButton()
+        if clicked not in (launch_btn, start_btn):
+            return
+
+        if diagnostic.start(game=name) is None:
+            QMessageBox.warning(self, "RigDoctor", "Couldn't start the capture.")
+            return
+        launched = steam.launch_game(appid) if clicked is launch_btn else False
+        self._diag_game = name
+        self._finish_btn.setEnabled(True)
+        self._discard_btn.setEnabled(True)
+        self._banner.show()
+        self._diag_timer.start()
+        self._poll_diag()
+        if clicked is launch_btn and not launched:
+            QMessageBox.information(
+                self, "RigDoctor",
+                "Recording started, but couldn't launch the game automatically — "
+                "launch it yourself, then click “Finish & analyze” when you're done.")
+
+    def _poll_diag(self) -> None:
+        from ..core import diagnostic
+
+        status = diagnostic.active()
+        if not status:
+            self._diag_timer.stop()  # recorder exited on its own
+            return
+        samples = status.get("samples", 0)
+        lost = "  ·  ⚠ GPU-lost detected" if status.get("gpu_lost") else ""
+        game = status.get("game") or self._diag_game or "your game"
+        self._banner_label.setText(
+            f"● Recording {game} — play it and reproduce the problem, then click "
+            f"“Finish & analyze”.   ({samples} samples{lost})"
+        )
+
+    def _finish_diagnostic(self) -> None:
+        self._diag_timer.stop()
+        self._finish_btn.setEnabled(False)
+        self._discard_btn.setEnabled(False)
+        self._banner_label.setText("Analyzing… (running the health report)")
+        threading.Thread(target=self._work_finish, daemon=True).start()
+
+    def _work_finish(self) -> None:
+        from ..core import diagnostic
+
+        try:
+            result = diagnostic.finish()
+        except Exception:
+            result = None
+        self._diag_done.emit(result)
+
+    def _on_diag_done(self, result) -> None:
+        self._banner.hide()
+        self._finish_btn.setEnabled(True)
+        self._discard_btn.setEnabled(True)
+        if result is None:
+            QMessageBox.warning(self, "RigDoctor", "The diagnostic couldn't be analyzed.")
+            return
+        DiagnosticDialog(result, self).exec()
+
+    def _discard_diagnostic(self) -> None:
+        from ..core import reccontrol
+
+        self._diag_timer.stop()
+        reccontrol.stop_background()
+        self._banner.hide()
+
+    # --- nav badge integration --------------------------------------------------------
+
+    def showEvent(self, event) -> None:  # noqa: N802 (Qt override)
+        # Viewing the list acknowledges the new games: clear the sidebar badge. The NEW
+        # tags stay on the rows for this session so the user can still spot them.
+        super().showEvent(event)
+        if self._new_appids:
+            from ..core import steam
+
+            threading.Thread(target=steam.acknowledge_new, daemon=True).start()
+            self.new_count_changed.emit(0)
+
+        # Reflect a capture that's still running (e.g. started earlier, navigated back).
+        from ..core import diagnostic
+
+        if diagnostic.is_running():
+            status = diagnostic.active() or {}
+            self._diag_game = status.get("game") or self._diag_game
+            self._banner.show()
+            if not self._diag_timer.isActive():
+                self._diag_timer.start()
@@ -0,0 +1,96 @@
+"""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 .widgets import finding_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:
+        self._run_btn.setEnabled(True)
+        if findings is None:  # collection failed — keep current results
+            self._status.setText("check failed")
+            return
+
+        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_card(finding))
+        self._list.addStretch(1)
@@ -2,36 +2,56 @@

 from __future__ import annotations

-from PySide6.QtCore import Qt
+import os
+import sys
+import threading
+
+from PySide6.QtCore import Qt, QProcess, QTimer, Signal
+from PySide6.QtGui import QTextDocument
 from PySide6.QtWidgets import (
+    QApplication,
    QButtonGroup,
+    QDialog,
    QFrame,
    QHBoxLayout,
    QLabel,
    QMainWindow,
+    QMessageBox,
    QPushButton,
    QStackedWidget,
+    QTextEdit,
    QVBoxLayout,
    QWidget,
 )

+from .. import __version__
+from ..config import load_config
+from ..core import alerts, elevation, updates
 from .dashboard import Dashboard
+from .environment_page import EnvironmentPage
+from .games_page import GamesPage
+from .health_page import HealthPage
+from .notifications_page import NotificationsPage
 from .recorder_page import RecorderPage
-from .theme import ACCENT, MUTED
+from .setup_page import SetupPage
+from .share_page import SharePage
+from .theme import ACCENT, GOOD, MUTED
 from .worker import SamplerWorker

-_NAV_ITEMS = ["Dashboard", "Logs", "Health", "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.",
-}
+_NAV_ITEMS = ["Dashboard", "Logs", "Health", "Games", "Environment", "Setup", "Notifications", "Share"]


 class MainWindow(QMainWindow):
+    _update_checked = Signal(object)  # (state, tag, notes)
+    _update_applied = Signal(int)     # pip exit code
+    _changelog_ready = Signal(object)  # ([(tag, date, notes)], error)
+    _elevated = Signal()              # privileged data collected at launch
+
    def __init__(self, interval: float = 1.0) -> None:
        super().__init__()
        self.setWindowTitle("RigDoctor")
        self.resize(1000, 680)
+        cfg = load_config()

        central = QWidget()
        self.setCentralWidget(central)
@@ -47,10 +67,22 @@ class MainWindow(QMainWindow):
        self._stack = QStackedWidget()
        self.dashboard = Dashboard()
        self.recorder_page = RecorderPage()
+        self.health_page = HealthPage()
+        self.games_page = GamesPage()
+        self.games_page.new_count_changed.connect(self._set_games_badge)
+        self.environment_page = EnvironmentPage()
+        self.setup_page = SetupPage()
+        self.notifications_page = NotificationsPage()
+        self.notifications_page.changed.connect(self._apply_alert_settings)
+        self.share_page = SharePage()
        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._placeholder_page("Inventory", _PLACEHOLDERS["Inventory"]))  # 3
+        self._stack.addWidget(self.health_page)          # 2 Health
+        self._stack.addWidget(self.games_page)           # 3 Games
+        self._stack.addWidget(self.environment_page)     # 4 Environment
+        self._stack.addWidget(self.setup_page)           # 5 Setup
+        self._stack.addWidget(self.notifications_page)   # 6 Notifications
+        self._stack.addWidget(self.share_page)           # 7 Share
        content_layout.addWidget(self._stack)

        layout.addWidget(self._build_sidebar())
@@ -58,8 +90,40 @@ class MainWindow(QMainWindow):

        self._worker = SamplerWorker(interval=interval)
        self._worker.sampled.connect(self.dashboard.update_sample)
+        # Desktop alerts (M8): overheat / GPU-lost from the sample stream, new-version below.
+        # Configurable on the Notifications page; gated by AlertMonitor.enabled.
+        self._notified_update_tag = None
+        self._alert_monitor = alerts.AlertMonitor(
+            gpu_temp=float(cfg.get("gpu_temp_alert", 90.0)),
+            cpu_temp=float(cfg.get("cpu_temp_alert", 95.0)),
+        )
+        self._alert_monitor.enabled = bool(cfg.get("alerts_enabled", True))
+        self._worker.sampled.connect(self._alert_monitor.check)
        self._worker.start()

+        # Ask for the password once at launch and collect root-only data (SMART +
+        # dmidecode); Health/Inventory then always show the full picture (config:
+        # elevate_on_launch). Falls back silently to non-root if cancelled/unavailable.
+        if cfg.get("elevate_on_launch", True) and elevation.available():
+            self._elevated.connect(self._on_elevated)
+            threading.Thread(target=self._collect_privileged, daemon=True).start()
+
+        # Update check (M13): once at launch, then periodically so a newly published
+        # release is detected without restarting (interval from config; 0 disables).
+        self._latest_tag = None
+        self._latest_notes = ""
+        self._applied = False
+        self._update_checked.connect(self._show_update_state)
+        self._update_applied.connect(self._on_update_applied)
+        self._changelog_ready.connect(self._on_changelog)
+        self._start_update_check()
+        minutes = float(cfg.get("update_check_minutes", 30) or 0)
+        if minutes > 0:
+            self._update_timer = QTimer(self)
+            self._update_timer.setInterval(int(minutes * 60_000))
+            self._update_timer.timeout.connect(self._start_update_check)
+            self._update_timer.start()
+
    def _build_sidebar(self) -> QFrame:
        bar = QFrame()
        bar.setObjectName("Sidebar")
@@ -78,6 +142,7 @@ class MainWindow(QMainWindow):

        group = QButtonGroup(self)
        group.setExclusive(True)
+        self._nav_buttons: dict[str, QPushButton] = {}
        for i, name in enumerate(_NAV_ITEMS):
            btn = QPushButton(name)
            btn.setObjectName("NavButton")
@@ -87,35 +152,173 @@ class MainWindow(QMainWindow):
            btn.clicked.connect(lambda _checked, idx=i: self._stack.setCurrentIndex(idx))
            group.addButton(btn, i)
            v.addWidget(btn)
+            self._nav_buttons[name] = btn

        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)
+        changelog_btn = QPushButton("Changelog")
+        changelog_btn.setObjectName("LinkButton")
+        changelog_btn.setCursor(Qt.CursorShape.PointingHandCursor)
+        changelog_btn.clicked.connect(self._show_changelog)
+        v.addWidget(changelog_btn)
+        check_btn = QPushButton("Check for updates")
+        check_btn.setObjectName("LinkButton")
+        check_btn.setCursor(Qt.CursorShape.PointingHandCursor)
+        check_btn.clicked.connect(self._manual_check)
+        v.addWidget(check_btn)
+
+        # 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)
+        self._restart_btn = QPushButton("Restart now")
+        self._restart_btn.setObjectName("PrimaryButton")
+        self._restart_btn.setCursor(Qt.CursorShape.PointingHandCursor)
+        self._restart_btn.clicked.connect(self._restart)
+        self._restart_btn.setVisible(False)
+        v.addWidget(self._restart_btn)
        return bar

-    def _placeholder_page(self, title: str, description: str) -> QWidget:
-        page = QWidget()
-        page.setObjectName("Page")
-        v = QVBoxLayout(page)
-        v.setContentsMargins(20, 18, 20, 18)
-        v.setSpacing(16)
-        head = QLabel(title)
-        head.setObjectName("PageTitle")
-        v.addWidget(head)
+    def _restart(self) -> None:
+        gui = os.path.join(os.path.dirname(sys.executable), "rigdoctor-gui")
+        if os.path.exists(gui):
+            QProcess.startDetached(gui)
+        else:  # dev / not installed next to python
+            QProcess.startDetached(sys.executable, sys.argv)
+        QApplication.instance().quit()

-        card = QFrame()
-        card.setObjectName("Card")
-        cv = QVBoxLayout(card)
-        cv.setContentsMargins(24, 48, 24, 48)
-        msg = QLabel(description)
-        msg.setObjectName("Muted")
-        msg.setWordWrap(True)
-        msg.setAlignment(Qt.AlignmentFlag.AlignCenter)
-        cv.addWidget(msg)
-        v.addWidget(card)
-        v.addStretch(1)
-        return page
+    def _apply_update(self) -> None:
+        if not self._latest_tag:
+            return
+        box = QMessageBox(self)
+        box.setWindowTitle(f"Update to {self._latest_tag}")
+        box.setText(f"Update RigDoctor to {self._latest_tag}?")
+        notes_doc = QTextDocument()
+        notes_doc.setMarkdown(self._latest_notes or "_(no release notes)_")
+        box.setInformativeText(notes_doc.toHtml())  # render Markdown as rich text (#1)
+        box.setStandardButtons(QMessageBox.StandardButton.Ok | QMessageBox.StandardButton.Cancel)
+        box.button(QMessageBox.StandardButton.Ok).setText("Update")
+        if box.exec() != QMessageBox.StandardButton.Ok:
+            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._applied = True
+            self._update_label.setText("update installed")
+            self._update_btn.setVisible(False)
+            self._restart_btn.setVisible(True)
+            if hasattr(self, "_update_timer"):
+                self._update_timer.stop()
+        else:
+            self._update_label.setText("update failed")
+            self._update_btn.setEnabled(True)
+
+    def _collect_privileged(self) -> None:
+        data = elevation.collect_via_pkexec()
+        if data is not None:
+            elevation.set_privileged(data)
+            self._elevated.emit()
+
+    def _on_elevated(self) -> None:
+        # Re-run Health now that root-only SMART data is available. (dmidecode is still
+        # collected and used by the relay guest view + the CLI `rigdoctor inventory`.)
+        self.health_page._run()
+
+    def _set_games_badge(self, count: int) -> None:
+        btn = self._nav_buttons.get("Games")
+        if btn is not None:
+            btn.setText(f"Games   ● {count}" if count > 0 else "Games")
+
+    def _apply_alert_settings(self) -> None:
+        cfg = load_config()
+        self._alert_monitor.enabled = bool(cfg.get("alerts_enabled", True))
+        self._alert_monitor.gpu_temp = float(cfg.get("gpu_temp_alert", 90.0))
+        self._alert_monitor.cpu_temp = float(cfg.get("cpu_temp_alert", 95.0))
+
+    def _manual_check(self) -> None:
+        if self._applied:
+            return
+        self._update_label.setText("checking for updates…")
+        self._start_update_check()
+
+    def _start_update_check(self) -> None:
+        threading.Thread(target=self._check_updates, daemon=True).start()
+
+    def _show_changelog(self) -> None:
+        dialog = QDialog(self)
+        dialog.setWindowTitle("RigDoctor — Changelog")
+        dialog.resize(560, 540)
+        layout = QVBoxLayout(dialog)
+        view = QTextEdit()
+        view.setObjectName("Report")
+        view.setReadOnly(True)
+        view.setPlainText("Loading…")
+        layout.addWidget(view)
+        self._changelog_view = view
+        dialog.show()
+        threading.Thread(target=self._fetch_changelog, daemon=True).start()
+
+    def _fetch_changelog(self) -> None:
+        self._changelog_ready.emit(updates.list_releases())
+
+    def _on_changelog(self, result) -> None:
+        view = getattr(self, "_changelog_view", None)
+        if view is None:
+            return
+        releases, error = result
+        if error == updates.NO_TOKEN:
+            view.setPlainText("Add an update token (Setup → Update access) to load the changelog.")
+            return
+        if error or not releases:
+            view.setPlainText("Couldn't load the changelog from the update server.")
+            return
+        blocks = []
+        for tag, date, notes in releases:
+            title = f"## {tag}" + (f" — {date}" if date else "")
+            blocks.append(f"{title}\n\n{notes or '_(no notes)_'}")
+        view.setMarkdown("\n\n".join(blocks))  # render Markdown instead of raw text (#1)
+
+    def _check_updates(self) -> None:
+        self._update_checked.emit(updates.update_state())
+
+    def _show_update_state(self, result) -> None:
+        if self._applied:  # an update was applied this session; awaiting restart
+            return
+        state, tag, notes = result
+        self._latest_tag = tag
+        self._latest_notes = notes
+        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)
+            if self._alert_monitor.enabled and tag != self._notified_update_tag:
+                self._notified_update_tag = tag  # once per version, not every poll
+                alerts.notify("Update available", f"RigDoctor {tag} is available — open RigDoctor to update.")
+        else:  # UP_TO_DATE
+            self._update_label.setText("up-to-date")

    def closeEvent(self, event) -> None:  # noqa: N802 (Qt override)
        self._worker.stop()
+        self.share_page.shutdown()
        super().closeEvent(event)
@@ -0,0 +1,108 @@
+"""Notifications page (M8 config): user-configurable alert settings."""
+
+from __future__ import annotations
+
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtWidgets import (
+    QCheckBox,
+    QDoubleSpinBox,
+    QFrame,
+    QGridLayout,
+    QHBoxLayout,
+    QLabel,
+    QPushButton,
+    QVBoxLayout,
+    QWidget,
+)
+
+from ..config import load_config, update_config
+from ..core import alerts
+
+
+class NotificationsPage(QWidget):
+    changed = Signal()  # settings saved — main window re-applies them live
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.setObjectName("Page")
+        root = QVBoxLayout(self)
+        root.setContentsMargins(20, 18, 20, 18)
+        root.setSpacing(16)
+
+        title = QLabel("Notifications")
+        title.setObjectName("PageTitle")
+        root.addWidget(title)
+
+        card = QFrame()
+        card.setObjectName("Card")
+        v = QVBoxLayout(card)
+        v.setContentsMargins(16, 14, 16, 14)
+        v.setSpacing(10)
+        head = QLabel("Alerts")
+        head.setStyleSheet("font-weight: 700; background: transparent;")
+        v.addWidget(head)
+
+        self._enabled = QCheckBox("Enable desktop notifications")
+        v.addWidget(self._enabled)
+
+        grid = QGridLayout()
+        grid.setHorizontalSpacing(12)
+        grid.setColumnStretch(2, 1)
+        self._gpu = self._spin()
+        self._cpu = self._spin()
+        grid.addWidget(QLabel("GPU temperature alert"), 0, 0)
+        grid.addWidget(self._gpu, 0, 1)
+        grid.addWidget(QLabel("CPU temperature alert"), 1, 0)
+        grid.addWidget(self._cpu, 1, 1)
+        v.addLayout(grid)
+
+        note = QLabel("GPU-lost and new-version alerts are included whenever notifications are enabled.")
+        note.setObjectName("Muted")
+        note.setWordWrap(True)
+        v.addWidget(note)
+
+        buttons = QHBoxLayout()
+        save = QPushButton("Save")
+        save.setObjectName("PrimaryButton")
+        save.clicked.connect(self._save)
+        test = QPushButton("Send test")
+        test.clicked.connect(self._test)
+        buttons.addWidget(save)
+        buttons.addWidget(test)
+        buttons.addStretch(1)
+        v.addLayout(buttons)
+        self._status = QLabel("")
+        self._status.setObjectName("Muted")
+        v.addWidget(self._status)
+
+        root.addWidget(card)
+        root.addStretch(1)
+        self._load()
+
+    @staticmethod
+    def _spin() -> QDoubleSpinBox:
+        spin = QDoubleSpinBox()
+        spin.setRange(40, 110)
+        spin.setDecimals(0)
+        spin.setSingleStep(1)
+        spin.setSuffix(" °C")
+        return spin
+
+    def _load(self) -> None:
+        cfg = load_config()
+        self._enabled.setChecked(bool(cfg.get("alerts_enabled", True)))
+        self._gpu.setValue(float(cfg.get("gpu_temp_alert", 90.0)))
+        self._cpu.setValue(float(cfg.get("cpu_temp_alert", 95.0)))
+
+    def _save(self) -> None:
+        update_config(
+            alerts_enabled=self._enabled.isChecked(),
+            gpu_temp_alert=self._gpu.value(),
+            cpu_temp_alert=self._cpu.value(),
+        )
+        self.changed.emit()
+        self._status.setText("Saved.")
+
+    def _test(self) -> None:
+        ok = alerts.notify("RigDoctor", "Test notification — alerts are working.")
+        self._status.setText("Test notification sent." if ok else "notify-send not found — install libnotify-bin (Setup).")
@@ -0,0 +1,239 @@
+"""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 (
+    QApplication,
+    QFrame,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QMessageBox,
+    QPushButton,
+    QSizePolicy,
+    QTextEdit,
+    QVBoxLayout,
+    QWidget,
+)
+
+from .. import config
+from ..core import installer, sysenv, uninstall, 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)
+
+        # Account access (M13/M12): one Gitea token gates updates and session sharing.
+        upd_card, upd_layout = _panel("Account access")
+        hint = QLabel("A Gitea access token unlocks updates and session sharing. "
+                      "Create it with scopes <b>read:user</b> and <b>read:repository</b>.")
+        hint.setObjectName("Muted")
+        hint.setWordWrap(True)
+        upd_layout.addWidget(hint)
+        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 (read:user + 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)
+
+        danger = QHBoxLayout()
+        danger.addStretch(1)
+        uninstall_btn = QPushButton("Uninstall RigDoctor")
+        uninstall_btn.setObjectName("DangerButton")
+        uninstall_btn.clicked.connect(self._uninstall)
+        danger.addWidget(uninstall_btn)
+        root.addLayout(danger)
+
+        self._refresh()
+        self._refresh_update_status()
+
+    def _uninstall(self) -> None:
+        box = QMessageBox(self)
+        box.setIcon(QMessageBox.Icon.Warning)
+        box.setWindowTitle("Uninstall RigDoctor")
+        box.setText("Uninstall RigDoctor?")
+        box.setInformativeText(
+            "This removes the app. Choose “Remove all” to also delete your settings, "
+            "update token, and captured logs."
+        )
+        remove_all = box.addButton("Remove all", QMessageBox.ButtonRole.DestructiveRole)
+        app_only = box.addButton("Uninstall", QMessageBox.ButtonRole.AcceptRole)
+        box.addButton("Cancel", QMessageBox.ButtonRole.RejectRole)
+        box.exec()
+        clicked = box.clickedButton()
+        if clicked is remove_all:
+            purge = True
+        elif clicked is app_only:
+            purge = False
+        else:
+            return
+        uninstall.uninstall(purge=purge)
+        QMessageBox.information(self, "RigDoctor", "Uninstalling… RigDoctor will close now.")
+        QApplication.instance().quit()
+
+    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, _notes) = 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>"
+        )
@@ -0,0 +1,348 @@
+"""Share page (M12): host or join a shared session over the relay.
+
+Guest sees the host's live sensors + health + inventory (read-only). If the host enables it,
+a full **PTY terminal** is shared: the guest types and the commands run on the host (as the
+host's user), the host reads along, and the host can type too — e.g. a sudo password, which
+stays local and is never sent to the guest.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+
+from PySide6.QtCore import Qt, QSocketNotifier, QTimer, QUrl
+from PySide6.QtWebSockets import QWebSocket
+from PySide6.QtWidgets import (
+    QCheckBox,
+    QFrame,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QPushButton,
+    QTextEdit,
+    QVBoxLayout,
+    QWidget,
+)
+
+from ..config import load_config, load_token
+from ..core import share
+from ..core.pty_session import PtySession
+from ..core.sampler import Sampler
+from ..core.sources import available_sources
+from .terminal_widget import TerminalView
+
+
+def _relay_url() -> str:
+    return load_config().get("relay_url", "wss://rigdoctor.jesseyvanofferen.com").rstrip("/")
+
+
+def _b64(data: bytes) -> str:
+    return base64.b64encode(data).decode("ascii")
+
+
+def _card(title: str) -> tuple[QFrame, QVBoxLayout]:
+    card = QFrame()
+    card.setObjectName("Card")
+    v = QVBoxLayout(card)
+    v.setContentsMargins(16, 14, 16, 14)
+    v.setSpacing(10)
+    head = QLabel(title)
+    head.setStyleSheet("font-weight: 700; background: transparent;")
+    v.addWidget(head)
+    return card, v
+
+
+class SharePage(QWidget):
+    def __init__(self) -> None:
+        super().__init__()
+        self.setObjectName("Page")
+        self._sampler = Sampler(available_sources())
+        self._host_ws: QWebSocket | None = None
+        self._guest_ws: QWebSocket | None = None
+        self._pty: PtySession | None = None
+        self._pty_notifier: QSocketNotifier | None = None
+        self._last_report = None
+        self._last_inv = None
+        self._timer = QTimer(self)
+        self._timer.setInterval(2000)
+        self._timer.timeout.connect(self._stream)
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(20, 18, 20, 18)
+        root.setSpacing(14)
+        title = QLabel("Share")
+        title.setObjectName("PageTitle")
+        root.addWidget(title)
+        root.addWidget(self._build_host())
+        root.addWidget(self._build_guest(), 1)
+
+    # ------------------------------------------------------------------ host
+    def _build_host(self) -> QFrame:
+        card, v = _card("Start a shared session")
+        self._host_status = QLabel("Let someone with an account view your machine, read-only.")
+        self._host_status.setObjectName("Muted")
+        self._host_status.setWordWrap(True)
+        v.addWidget(self._host_status)
+
+        row = QHBoxLayout()
+        self._start_btn = QPushButton("Start shared session")
+        self._start_btn.setObjectName("PrimaryButton")
+        self._start_btn.clicked.connect(self._start_host)
+        self._stop_btn = QPushButton("Stop")
+        self._stop_btn.setEnabled(False)
+        self._stop_btn.clicked.connect(self._stop_host)
+        self._code_label = QLabel("")
+        self._code_label.setStyleSheet("font-weight:700; font-size:18px; color:#38bdf8; background:transparent;")
+        self._code_label.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+        row.addWidget(self._start_btn)
+        row.addWidget(self._stop_btn)
+        row.addSpacing(12)
+        row.addWidget(self._code_label)
+        row.addStretch(1)
+        v.addLayout(row)
+
+        self._allow_term = QCheckBox("Allow remote terminal — the guest runs commands as your user (you read along; you can type too, e.g. a sudo password)")
+        self._allow_term.setStyleSheet("color:#fb923c; background:transparent;")
+        self._allow_term.toggled.connect(self._toggle_terminal)
+        v.addWidget(self._allow_term)
+
+        self._host_term = TerminalView()
+        self._host_term.keys.connect(lambda b: self._pty.write(b) if self._pty else None)
+        self._host_term.resized.connect(lambda r, c: self._pty.set_size(r, c) if self._pty else None)
+        self._host_term.setVisible(False)
+        v.addWidget(self._host_term)
+        return card
+
+    def _start_host(self) -> None:
+        if not load_token():
+            self._host_status.setText("Set a Gitea access token in Setup → Account access first.")
+            return
+        self._host_status.setText("Connecting to the relay…")
+        self._start_btn.setEnabled(False)
+        self._host_ws = QWebSocket()
+        self._host_ws.connected.connect(lambda: self._host_ws.sendTextMessage(json.dumps({"token": load_token()})))
+        self._host_ws.textMessageReceived.connect(self._host_msg)
+        self._host_ws.disconnected.connect(self._host_closed)
+        self._host_ws.errorOccurred.connect(lambda *_: self._host_status.setText(f"Relay error: {self._host_ws.errorString()}"))
+        self._host_ws.open(QUrl(_relay_url() + "/ws/host"))
+
+    def _host_msg(self, text: str) -> None:
+        try:
+            data = json.loads(text)
+        except ValueError:
+            return
+        if data.get("error"):
+            self._host_status.setText(f"Rejected: {data['error']}")
+            return
+        if "code" in data:  # relay handshake
+            self._code_label.setText(data["code"])
+            self._host_status.setText(f"Sharing as {data.get('user', '?')} — give this code to whoever should view your machine.")
+            self._stop_btn.setEnabled(True)
+            self._host_ws.sendTextMessage(share.host_full_frame(self._sampler))
+            self._send_terminal_state()
+            if self._allow_term.isChecked():
+                self._start_pty()
+            self._timer.start()
+            return
+        kind = data.get("type")  # frames forwarded from a guest
+        if kind == "req_full":
+            # A guest just joined — send a full frame AND the current terminal state, so a
+            # guest that joins *after* the host enabled the terminal still gets access.
+            self._host_ws.sendTextMessage(share.host_full_frame(self._sampler))
+            self._send_terminal_state()
+        elif kind == "pty_in" and self._pty:
+            self._pty.write(base64.b64decode(data["data"]))
+        elif kind == "pty_resize" and self._pty:
+            self._pty.set_size(int(data["rows"]), int(data["cols"]))
+
+    def _toggle_terminal(self, on: bool) -> None:
+        if on and self._host_ws and self._code_label.text():
+            self._start_pty()
+        elif not on:
+            self._stop_pty()
+        self._send_terminal_state()
+
+    def _send_terminal_state(self) -> None:
+        if self._host_ws and self._code_label.text():
+            self._host_ws.sendTextMessage(json.dumps({"type": "terminal", "enabled": self._allow_term.isChecked()}))
+
+    def _start_pty(self) -> None:
+        if self._pty:
+            return
+        rows, cols = self._host_term.grid()
+        self._pty = PtySession(rows=rows, cols=cols)
+        self._pty_notifier = QSocketNotifier(self._pty.master_fd, QSocketNotifier.Type.Read, self)
+        self._pty_notifier.activated.connect(self._on_pty_output)
+        self._host_term.reset()
+        self._host_term.setVisible(True)
+
+    def _on_pty_output(self) -> None:
+        if not self._pty:
+            return
+        data = self._pty.read()
+        if not data:  # shell exited / EOF
+            self._stop_pty()
+            self._send_terminal_state()
+            self._allow_term.setChecked(False)
+            return
+        self._host_term.feed(data)
+        if self._host_ws:
+            self._host_ws.sendTextMessage(json.dumps({"type": "pty", "data": _b64(data)}))
+
+    def _stop_pty(self) -> None:
+        if self._pty_notifier:
+            self._pty_notifier.setEnabled(False)
+            self._pty_notifier = None
+        if self._pty:
+            self._pty.close()
+            self._pty = None
+        self._host_term.setVisible(False)
+
+    def _stream(self) -> None:
+        if self._host_ws:
+            self._host_ws.sendTextMessage(share.host_snapshot_frame(self._sampler))
+
+    def _stop_host(self) -> None:
+        self._timer.stop()
+        self._stop_pty()
+        if self._host_ws:
+            self._host_ws.close()
+            self._host_ws = None
+        self._code_label.setText("")
+        self._stop_btn.setEnabled(False)
+        self._start_btn.setEnabled(True)
+        self._host_status.setText("Stopped sharing.")
+
+    def _host_closed(self) -> None:
+        self._timer.stop()
+        self._stop_pty()
+        self._start_btn.setEnabled(True)
+        self._stop_btn.setEnabled(False)
+        if self._code_label.text():
+            self._code_label.setText("")
+            self._host_status.setText("Disconnected from the relay.")
+
+    # ----------------------------------------------------------------- guest
+    def _build_guest(self) -> QFrame:
+        card, v = _card("Join a shared session")
+        row = QHBoxLayout()
+        self._code_input = QLineEdit()
+        self._code_input.setPlaceholderText("Enter share code")
+        self._code_input.setMaxLength(6)
+        self._code_input.setFixedWidth(160)
+        self._join_btn = QPushButton("Join")
+        self._join_btn.setObjectName("PrimaryButton")
+        self._join_btn.clicked.connect(self._join)
+        self._leave_btn = QPushButton("Leave")
+        self._leave_btn.setEnabled(False)
+        self._leave_btn.clicked.connect(self._leave)
+        row.addWidget(self._code_input)
+        row.addWidget(self._join_btn)
+        row.addWidget(self._leave_btn)
+        row.addStretch(1)
+        v.addLayout(row)
+        self._guest_status = QLabel("")
+        self._guest_status.setObjectName("Muted")
+        v.addWidget(self._guest_status)
+
+        self._view = QTextEdit()
+        self._view.setObjectName("Report")
+        self._view.setReadOnly(True)
+        self._view.setVisible(False)
+        self._view.setMinimumHeight(200)
+        v.addWidget(self._view)
+
+        self._term_label = QLabel("")
+        self._term_label.setObjectName("Muted")
+        self._term_label.setVisible(False)
+        v.addWidget(self._term_label)
+        self._guest_term = TerminalView()
+        self._guest_term.keys.connect(self._guest_key)
+        self._guest_term.resized.connect(self._guest_resize)
+        self._guest_term.setVisible(False)
+        v.addWidget(self._guest_term)
+        return card
+
+    def _join(self) -> None:
+        code = self._code_input.text().strip().upper()
+        if not load_token():
+            self._guest_status.setText("Set a Gitea access token in Setup → Account access first.")
+            return
+        if not code:
+            self._guest_status.setText("Enter a share code.")
+            return
+        self._guest_status.setText("Connecting…")
+        self._join_btn.setEnabled(False)
+        self._guest_ws = QWebSocket()
+        self._guest_ws.connected.connect(lambda: self._guest_ws.sendTextMessage(json.dumps({"token": load_token()})))
+        self._guest_ws.textMessageReceived.connect(self._guest_msg)
+        self._guest_ws.disconnected.connect(self._guest_closed)
+        self._guest_ws.errorOccurred.connect(lambda *_: self._guest_status.setText(f"Relay error: {self._guest_ws.errorString()}"))
+        self._guest_ws.open(QUrl(_relay_url() + "/ws/guest/" + code))
+
+    def _guest_msg(self, text: str) -> None:
+        try:
+            data = json.loads(text)
+        except ValueError:
+            return
+        if data.get("error"):
+            self._guest_status.setText(data["error"])
+            return
+        if "joined" in data:
+            self._guest_status.setText(f"Viewing {data.get('host', '?')}'s machine — read-only.")
+            self._leave_btn.setEnabled(True)
+            self._view.setVisible(True)
+            self._guest_ws.sendTextMessage(json.dumps({"type": "req_full"}))
+            return
+        kind = data.get("type")
+        if kind in ("full", "snapshot"):
+            if kind == "full":
+                self._last_report = data.get("report")
+                self._last_inv = data.get("inventory")
+            self._view.setHtml(share.guest_html(data.get("snapshot"), self._last_report, self._last_inv))
+        elif kind == "terminal":
+            self._set_terminal_visible(bool(data.get("enabled")))
+        elif kind == "pty":
+            self._guest_term.feed(base64.b64decode(data["data"]))
+
+    def _set_terminal_visible(self, enabled: bool) -> None:
+        self._term_label.setVisible(True)
+        self._term_label.setText("Terminal enabled by host — your keystrokes run on their machine. Click here and type."
+                                 if enabled else "Terminal not enabled by the host.")
+        self._guest_term.setVisible(enabled)
+        if enabled:
+            self._guest_term.reset()
+            self._guest_resize(*self._guest_term.grid())
+            self._guest_term.setFocus()
+
+    def _guest_key(self, data: bytes) -> None:
+        if self._guest_ws:
+            self._guest_ws.sendTextMessage(json.dumps({"type": "pty_in", "data": _b64(data)}))
+
+    def _guest_resize(self, rows: int, cols: int) -> None:
+        if self._guest_ws:
+            self._guest_ws.sendTextMessage(json.dumps({"type": "pty_resize", "rows": rows, "cols": cols}))
+
+    def _leave(self) -> None:
+        if self._guest_ws:
+            self._guest_ws.close()
+            self._guest_ws = None
+        for w in (self._view, self._term_label, self._guest_term):
+            w.setVisible(False)
+        self._leave_btn.setEnabled(False)
+        self._join_btn.setEnabled(True)
+        self._guest_status.setText("Left the session.")
+
+    def _guest_closed(self) -> None:
+        self._join_btn.setEnabled(True)
+        self._leave_btn.setEnabled(False)
+        if self._view.isVisible():
+            self._guest_status.setText("Session ended (host disconnected).")
+
+    def shutdown(self) -> None:
+        self._timer.stop()
+        self._stop_pty()
+        for ws in (self._host_ws, self._guest_ws):
+            if ws:
+                ws.close()
@@ -0,0 +1,98 @@
+"""A minimal terminal view: renders PTY output via pyte and emits keystrokes (M12, Tier 3).
+
+Used by both sides of a shared session — the host (mirrors its local PTY, can also type, e.g.
+a sudo password) and the guest (renders the streamed PTY, sends keystrokes). Monochrome for
+now; cursor addressing / layout (vim, top) work via pyte.
+"""
+
+from __future__ import annotations
+
+import pyte
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtGui import QFontDatabase, QFontMetrics, QTextCursor
+from PySide6.QtWidgets import QPlainTextEdit
+
+
+class TerminalView(QPlainTextEdit):
+    keys = Signal(bytes)        # user keystrokes -> bytes for the PTY
+    resized = Signal(int, int)  # rows, cols
+
+    def __init__(self, rows: int = 24, cols: int = 80):
+        super().__init__()
+        self.setLineWrapMode(QPlainTextEdit.LineWrapMode.NoWrap)
+        self.setFont(QFontDatabase.systemFont(QFontDatabase.SystemFont.FixedFont))
+        self.setUndoRedoEnabled(False)
+        self.setMinimumHeight(260)
+        self._rows, self._cols = rows, cols
+        self._screen = pyte.HistoryScreen(cols, rows, history=1000, ratio=0.5)
+        self._stream = pyte.ByteStream(self._screen)
+
+    def grid(self) -> tuple[int, int]:
+        return self._rows, self._cols
+
+    def feed(self, data: bytes) -> None:
+        self._stream.feed(data)
+        self._render()
+
+    def reset(self) -> None:
+        self._screen.reset()
+        self._render()
+
+    def _row_text(self, row) -> str:
+        return "".join(row[x].data for x in range(self._cols)).rstrip()
+
+    def _render(self) -> None:
+        bar = self.verticalScrollBar()
+        at_bottom = bar.value() >= bar.maximum() - 2
+        prev = bar.value()
+        history = [self._row_text(r) for r in self._screen.history.top]  # scrollback
+        self.setPlainText("\n".join(history + list(self._screen.display)))
+        if at_bottom:  # follow output; place caret at the real (row, col)
+            cursor = self.textCursor()
+            cursor.movePosition(QTextCursor.MoveOperation.Start)
+            cursor.movePosition(QTextCursor.MoveOperation.Down, QTextCursor.MoveMode.MoveAnchor, len(history) + self._screen.cursor.y)
+            cursor.movePosition(QTextCursor.MoveOperation.Right, QTextCursor.MoveMode.MoveAnchor, self._screen.cursor.x)
+            self.setTextCursor(cursor)
+            self.ensureCursorVisible()
+        else:  # user scrolled up to read — keep their place
+            bar.setValue(prev)
+
+    def resizeEvent(self, event):  # noqa: N802 (Qt override)
+        super().resizeEvent(event)
+        fm = QFontMetrics(self.font())
+        cw = max(1, fm.horizontalAdvance("M"))
+        ch = max(1, fm.height())
+        cols = max(20, self.viewport().width() // cw)
+        rows = max(6, self.viewport().height() // ch)
+        if (rows, cols) != (self._rows, self._cols):
+            self._rows, self._cols = rows, cols
+            self._screen.resize(rows, cols)
+            self._render()
+            self.resized.emit(rows, cols)
+
+    def keyPressEvent(self, event):  # noqa: N802 (Qt override)
+        data = self._translate(event)
+        if data:
+            self.keys.emit(data)
+        event.accept()  # display comes from PTY output, not local editing
+
+    @staticmethod
+    def _translate(event) -> bytes:
+        key = event.key()
+        mod = event.modifiers()
+        k = Qt.Key
+        if mod & Qt.KeyboardModifier.ControlModifier and k.Key_A.value <= key <= k.Key_Z.value:
+            return bytes([key - k.Key_A.value + 1])  # Ctrl-A..Ctrl-Z
+        special = {
+            k.Key_Return.value: b"\r", k.Key_Enter.value: b"\r",
+            k.Key_Backspace.value: b"\x7f", k.Key_Tab.value: b"\t",
+            k.Key_Escape.value: b"\x1b",
+            k.Key_Up.value: b"\x1b[A", k.Key_Down.value: b"\x1b[B",
+            k.Key_Right.value: b"\x1b[C", k.Key_Left.value: b"\x1b[D",
+            k.Key_Home.value: b"\x1b[H", k.Key_End.value: b"\x1b[F",
+            k.Key_Delete.value: b"\x1b[3~", k.Key_PageUp.value: b"\x1b[5~", k.Key_PageDown.value: b"\x1b[6~",
+        }
+        if key in special:
+            return special[key]
+        text = event.text()
+        return text.encode("utf-8") if text else b""
@@ -2,6 +2,10 @@

 from __future__ import annotations

+from pathlib import Path
+
+_CHECK = (Path(__file__).parent / "assets" / "check.svg").as_posix()
+
 # Palette (dark)
 BG = "#101216"
 SIDEBAR = "#15181e"
@@ -10,6 +14,7 @@ CARD_BORDER = "#2a2f39"
 TRACK = "#2a2f39"
 TEXT = "#e6e8eb"
 MUTED = "#8b929c"
+INPUT_BG = "#0d0f13"  # form-control background (must stay dark — see contrast rule)

 ACCENT = "#38bdf8"
 COLD = "#7dd3fc"  # icey-blue
@@ -99,6 +104,15 @@ QPushButton#PrimaryButton {{ background: {ACCENT}; color: #06222e; border: none;
 QPushButton#PrimaryButton:hover {{ background: #5cc8fb; }}
 QPushButton#PrimaryButton:disabled {{ background: #27424f; color: #5f7c8a; }}

+/* Inline per-finding action buttons (Install / Apply). Outlined: bright accent text on the
+   dark card so it stays readable regardless of fill painting; fills accent on hover. */
+QPushButton#ActionButton {{
+    background: transparent; color: {ACCENT}; border: 1px solid {ACCENT};
+    border-radius: 8px; padding: 6px 16px; font-weight: 700; min-height: 18px;
+}}
+QPushButton#ActionButton:hover {{ background: {ACCENT}; color: #06222e; }}
+QPushButton#ActionButton:disabled {{ color: {MUTED}; border-color: {CARD_BORDER}; }}
+
 QDoubleSpinBox, QSpinBox {{
    background: #262b34; color: {TEXT}; border: 1px solid {CARD_BORDER};
    border-radius: 6px; padding: 4px 6px;
@@ -107,4 +121,51 @@ QDoubleSpinBox, QSpinBox {{
 QTextEdit#Report {{
    background: #0d0f13; color: #cfd3da; border: 1px solid {CARD_BORDER}; border-radius: 8px;
 }}
+
+QPushButton#DangerButton {{
+    background: transparent; color: {CRIT}; border: 1px solid {CRIT};
+    border-radius: 8px; padding: 7px 14px;
+}}
+QPushButton#DangerButton:hover {{ background: {CRIT}; color: #1a0d0d; }}
+
+QPushButton#LinkButton {{
+    background: transparent; border: none; color: {MUTED};
+    text-align: left; padding: 0; text-decoration: underline;
+}}
+QPushButton#LinkButton:hover {{ color: {TEXT}; }}
+
+QCheckBox {{ spacing: 8px; background: transparent; }}
+QCheckBox::indicator {{
+    width: 17px; height: 17px; border-radius: 4px;
+    border: 1px solid {MUTED}; background: #262b34;
+}}
+QCheckBox::indicator:hover {{ border-color: {ACCENT}; }}
+QCheckBox::indicator:checked {{
+    background: {ACCENT}; border-color: {ACCENT}; image: url("{_CHECK}");
+}}
+
+/* Dialogs (update prompt, changelog) — match the dark theme so text is readable. */
+QDialog {{ background: {BG}; }}
+QMessageBox {{ background: {CARD}; }}
+QDialog QLabel, QMessageBox QLabel {{ color: {TEXT}; background: transparent; }}
+
+/* Form controls: keep dark bg + light text (Fusion defaults to light-on-light here). */
+QLineEdit, QPlainTextEdit, QAbstractSpinBox, QComboBox {{
+    background: {INPUT_BG}; color: {TEXT};
+    border: 1px solid {CARD_BORDER}; border-radius: 6px; padding: 5px 8px;
+    selection-background-color: {ACCENT}; selection-color: #06222e;
+}}
+QLineEdit:focus, QPlainTextEdit:focus, QAbstractSpinBox:focus, QComboBox:focus {{
+    border: 1px solid {ACCENT};
+}}
+QLineEdit:disabled, QPlainTextEdit:disabled, QAbstractSpinBox:disabled {{ color: {MUTED}; }}
+
+/* The combo-box drop-down list is a separate popup view — unstyled it renders
+   light-on-light (same Fusion trap as the closed control above). */
+QComboBox QAbstractItemView {{
+    background: {CARD}; color: {TEXT};
+    border: 1px solid {CARD_BORDER}; outline: 0;
+    selection-background-color: {ACCENT}; selection-color: #06222e;
+}}
+QComboBox QAbstractItemView::item {{ padding: 5px 8px; min-height: 22px; }}
 """
@@ -2,9 +2,12 @@

 from __future__ import annotations

-from PySide6.QtCore import QRectF, Qt
-from PySide6.QtGui import QColor, QFont, QPainter, QPen
+from collections import deque
+
+from PySide6.QtCore import QPointF, QRectF, Qt
+from PySide6.QtGui import QColor, QFont, QPainter, QPainterPath, QPen
 from PySide6.QtWidgets import (
+    QComboBox,
    QFrame,
    QHBoxLayout,
    QLabel,
@@ -16,7 +19,118 @@ from PySide6.QtWidgets import (

 from ..core.sample import Reading
 from ..render import format_value
-from .theme import MUTED, TEXT, TRACK, gauge_color, temp_color
+from .theme import (
+    ACCENT,
+    CRIT,
+    GOOD,
+    MUTED,
+    TEMP_WARN,
+    TEXT,
+    TRACK,
+    USAGE_WARN,
+    WARN,
+    gauge_color,
+    temp_color,
+)
+
+_SEV = {
+    "critical": ("CRITICAL", CRIT),
+    "warning": ("WARNING", WARN),
+    "info": ("INFO", MUTED),
+    "ok": ("OK", GOOD),
+}
+
+
+def finding_card(finding, on_install=None, on_apply=None) -> QFrame:
+    """A card for one M4/M6 Finding (severity-colored title, detail, suggested fix).
+
+    If the finding names an installable catalog component (``finding.action``) and an
+    ``on_install(component)`` callback is given, an "Install" button is shown — so a
+    "tool not installed" finding becomes one click instead of a copy-pasted apt command.
+
+    If the finding names a runtime tunable (``finding.fix``) and an ``on_apply(fix_id,
+    value)`` callback is given, a dropdown of the live options + an Apply button is shown
+    (M6 live fixes — D22).
+    """
+    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)
+
+    component = _installable_component(finding) if on_install else None
+    if component is not None:
+        row = QHBoxLayout()
+        row.addStretch(1)
+        btn = QPushButton(f"Install {component.name}")
+        btn.setObjectName("ActionButton")
+        btn.setCursor(Qt.CursorShape.PointingHandCursor)
+        btn.clicked.connect(lambda: on_install(component))
+        row.addWidget(btn)
+        v.addLayout(row)
+
+    tunable = _tunable(finding) if on_apply else None
+    if tunable is not None and tunable.options:
+        row = QHBoxLayout()
+        name = QLabel(f"{tunable.label}:")
+        name.setObjectName("Muted")
+        combo = QComboBox()
+        combo.addItems(tunable.options)
+        if tunable.current in tunable.options:
+            combo.setCurrentText(tunable.current)
+        combo.setCursor(Qt.CursorShape.PointingHandCursor)
+        apply_btn = QPushButton("Apply")
+        apply_btn.setObjectName("ActionButton")
+        apply_btn.setCursor(Qt.CursorShape.PointingHandCursor)
+        apply_btn.clicked.connect(lambda: on_apply(tunable.id, combo.currentText()))
+        row.addWidget(name)
+        row.addWidget(combo, 1)
+        row.addWidget(apply_btn)
+        v.addLayout(row)
+        if tunable.note:
+            note = QLabel(tunable.note)
+            note.setObjectName("Muted")
+            v.addWidget(note)
+    return card
+
+
+def _tunable(finding):
+    """The runtime tunable a finding can apply, if any."""
+    fix = getattr(finding, "fix", "")
+    if not fix:
+        return None
+    from ..core import fixes
+
+    return fixes.get_tunable(fix)
+
+
+def _installable_component(finding):
+    """The catalog component a finding offers to install, if any and if apt is usable."""
+    action = getattr(finding, "action", "")
+    if not action:
+        return None
+    from ..core import catalog, sysenv
+
+    if sysenv.package_manager() != "apt":
+        return None  # apt-only (D15) — no one-click install elsewhere
+    return catalog.by_id(action)


 class Card(QFrame):
@@ -148,6 +262,117 @@ class StatGauge(QWidget):
        p.end()


+class HistoryGraph(QWidget):
+    """A headline metric as a trend: current value + window min/max + a history line.
+
+    Replaces the at-a-glance gauge with changes-over-time. `kind` drives the color
+    (temp band / usage / accent), matching StatGauge so the dashboard stays consistent.
+    """
+
+    def __init__(self, title: str, unit: str = "", vmin: float = 0.0, vmax: float = 100.0,
+                 kind: str = "accent", history: int = 180) -> None:
+        super().__init__()
+        self._title = title
+        self._unit = unit
+        self._min = vmin
+        self._max = vmax
+        self._kind = kind  # "temp" | "usage" | "accent"
+        self._values: deque[float | None] = deque(maxlen=history)
+        self.setMinimumSize(160, 132)
+
+    def add_value(self, value: float | None) -> None:
+        self._values.append(value)
+        self.update()
+
+    def _fmt(self, value: float | None) -> str:
+        if value is None:
+            return "—"
+        if self._unit == "°C":
+            return f"{value:.0f}°"
+        if self._unit == "%":
+            return f"{value:.0f}%"
+        return f"{value:.0f}{self._unit}"
+
+    def paintEvent(self, event) -> None:  # noqa: N802 (Qt override)
+        p = QPainter(self)
+        p.setRenderHint(QPainter.RenderHint.Antialiasing)
+        w, h = self.width(), self.height()
+        pad = 10.0
+        present = [v for v in self._values if v is not None]
+        current = next((v for v in reversed(self._values) if v is not None), None)
+        color = QColor(gauge_color(self._kind, current))
+
+        ftitle = QFont()
+        ftitle.setPointSizeF(10.0)
+        ftitle.setBold(True)
+        p.setFont(ftitle)
+        p.setPen(QColor(MUTED))
+        p.drawText(QRectF(pad, 6, w - 2 * pad, 18),
+                   Qt.AlignmentFlag.AlignLeft | Qt.AlignmentFlag.AlignVCenter, self._title)
+
+        fval = QFont()
+        fval.setPointSizeF(21.0)
+        fval.setBold(True)
+        p.setFont(fval)
+        p.setPen(color if current is not None else QColor(MUTED))
+        p.drawText(QRectF(pad, 2, w - 2 * pad, 28),
+                   Qt.AlignmentFlag.AlignRight | Qt.AlignmentFlag.AlignTop, self._fmt(current))
+
+        if present:
+            fsm = QFont()
+            fsm.setPointSizeF(8.5)
+            p.setFont(fsm)
+            p.setPen(QColor(MUTED))
+            p.drawText(QRectF(pad, 27, w - 2 * pad, 14), Qt.AlignmentFlag.AlignLeft,
+                       f"min {self._fmt(min(present))}   max {self._fmt(max(present))}")
+
+        g_top, g_bot = 48.0, h - pad
+        g_left, g_right = pad, w - pad
+        span = self._max - self._min
+        if g_bot - g_top < 12 or g_right - g_left < 12 or span <= 0:
+            p.end()
+            return
+
+        def y_of(v: float) -> float:
+            frac = (max(self._min, min(self._max, v)) - self._min) / span
+            return g_bot - frac * (g_bot - g_top)
+
+        warn = TEMP_WARN if self._kind == "temp" else (USAGE_WARN if self._kind == "usage" else None)
+        if warn is not None and self._min <= warn <= self._max:
+            pen = QPen(QColor(TRACK))
+            pen.setWidthF(1.0)
+            pen.setStyle(Qt.PenStyle.DashLine)
+            p.setPen(pen)
+            yw = y_of(warn)
+            p.drawLine(QPointF(g_left, yw), QPointF(g_right, yw))
+
+        maxlen = self._values.maxlen or 1
+        step = (g_right - g_left) / max(1, maxlen - 1)
+        n = len(self._values)
+        # Build the line newest-at-right; break it where readings are missing.
+        path = QPainterPath()
+        drawing = False
+        for i, v in enumerate(self._values):
+            if v is None:
+                drawing = False
+                continue
+            x = g_right - (n - 1 - i) * step
+            y = y_of(v)
+            if drawing:
+                path.lineTo(x, y)
+            else:
+                path.moveTo(x, y)
+                drawing = True
+        if not path.isEmpty():
+            pen = QPen(color)
+            pen.setWidthF(2.0)
+            pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+            pen.setJoinStyle(Qt.PenJoinStyle.RoundJoin)
+            p.setPen(pen)
+            p.drawPath(path)
+        p.end()
+
+
 class MetricBar(QWidget):
    """A label + value with a thin progress bar (for 0–100% metrics)."""

@@ -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, title: str = "Health report") -> str:
+    if not findings:
+        return f"{title}: 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 = [title, "", 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 ""
@@ -0,0 +1,38 @@
+"""Tests for the M8 alert monitor (edge-triggered; notify mocked)."""
+
+import unittest
+from unittest import mock
+
+from rigdoctor.core import alerts
+from rigdoctor.core.sample import Reading, Sample
+
+
+def _gpu(temp):
+    return Sample(readings=[Reading("gpu", "temp", temp, "°C")])
+
+
+class AlertTests(unittest.TestCase):
+    @mock.patch.object(alerts, "notify")
+    def test_edge_triggered_no_repeat(self, m):
+        mon = alerts.AlertMonitor(gpu_temp=90.0, cooldown=0.0)
+        mon.check(_gpu(95))   # fires
+        mon.check(_gpu(96))   # still hot — no repeat while active
+        self.assertEqual(m.call_count, 1)
+        mon.check(_gpu(50))   # clears
+        mon.check(_gpu(95))   # hot again — fires
+        self.assertEqual(m.call_count, 2)
+
+    @mock.patch.object(alerts, "notify")
+    def test_no_alert_below_threshold(self, m):
+        alerts.AlertMonitor(gpu_temp=90.0).check(_gpu(70))
+        m.assert_not_called()
+
+    @mock.patch.object(alerts, "notify")
+    def test_gpu_lost(self, m):
+        mon = alerts.AlertMonitor()
+        mon.check(Sample(readings=[Reading("gpu", "status", None, "", "query-timeout")]))
+        m.assert_called_once()
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,42 @@
+"""Tests for config save/load (flat TOML writer)."""
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from rigdoctor import config
+
+
+class ConfigTests(unittest.TestCase):
+    def test_save_load_round_trip(self):
+        with tempfile.TemporaryDirectory() as d:
+            cf = Path(d) / "config.toml"
+            with mock.patch.object(config, "CONFIG_FILE", cf), mock.patch.object(config, "CONFIG_DIR", Path(d)):
+                config.save_config({"alerts_enabled": False, "gpu_temp_alert": 88.0, "update_check_minutes": 5})
+                loaded = config.load_config()
+                self.assertIs(loaded["alerts_enabled"], False)
+                self.assertEqual(loaded["gpu_temp_alert"], 88.0)
+                self.assertEqual(loaded["update_check_minutes"], 5)
+
+    def test_list_value_round_trip(self):
+        with tempfile.TemporaryDirectory() as d:
+            cf = Path(d) / "config.toml"
+            with mock.patch.object(config, "CONFIG_FILE", cf), mock.patch.object(config, "CONFIG_DIR", Path(d)):
+                paths = ["/home/u/.local/share/Steam", "/mnt/games/SteamLibrary"]
+                config.update_config(steam_libraries=paths)
+                self.assertEqual(config.load_config()["steam_libraries"], paths)
+                config.update_config(steam_libraries=[])
+                self.assertEqual(config.load_config()["steam_libraries"], [])
+
+    def test_update_config_merges_and_keeps_defaults(self):
+        with tempfile.TemporaryDirectory() as d:
+            cf = Path(d) / "config.toml"
+            with mock.patch.object(config, "CONFIG_FILE", cf), mock.patch.object(config, "CONFIG_DIR", Path(d)):
+                config.update_config(cpu_temp_alert=70.0)
+                self.assertEqual(config.load_config()["cpu_temp_alert"], 70.0)
+                self.assertEqual(config.load_config()["gpu_temp_alert"], 90.0)  # default preserved
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,61 @@
+"""Tests for the guided diagnostic orchestration (M3+M4 glue)."""
+
+import tempfile
+import time
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from rigdoctor.core import diagnostic
+from rigdoctor.core.crashlog import CrashLogWriter, summarize
+from rigdoctor.core.health import Finding
+from rigdoctor.core.sample import Reading, Sample
+
+
+def _write_log(path: str, game: str) -> None:
+    w = CrashLogWriter(path)
+    w.write_event("session-start", "interval=1s")
+    w.write_event("game", game)
+    for temp in (60.0, 72.0, 81.0):
+        w.write_sample(Sample(ts=time.time(), readings=[Reading("gpu", "temp", temp, "°C", "")]))
+    w.write_event("gpu-lost", "nvidia-smi query timed out")
+    w.close()
+
+
+class GameRecoveryTests(unittest.TestCase):
+    def test_game_recovered_from_log_event(self):
+        with tempfile.TemporaryDirectory() as d:
+            log = str(Path(d) / "capture.jsonl")
+            _write_log(log, "Path of Exile 2")
+            summary = summarize(log)
+            self.assertEqual(diagnostic._game_from_summary(summary), "Path of Exile 2")
+
+    def test_no_game_event_returns_none(self):
+        with tempfile.TemporaryDirectory() as d:
+            log = str(Path(d) / "capture.jsonl")
+            w = CrashLogWriter(log)
+            w.write_event("session-start")
+            w.close()
+            self.assertIsNone(diagnostic._game_from_summary(summarize(log)))
+
+
+class FinishTests(unittest.TestCase):
+    def test_finish_combines_summary_and_findings(self):
+        with tempfile.TemporaryDirectory() as d:
+            log = Path(d) / "capture.jsonl"
+            _write_log(str(log), "Satisfactory")
+            fake = [Finding("warning", "GPU", "NVIDIA Xid 79 ×1", "fell off the bus")]
+            with mock.patch("rigdoctor.core.health.run_health_checks", return_value=fake), \
+                 mock.patch.object(diagnostic.reccontrol, "stop_background", return_value=False), \
+                 mock.patch.object(diagnostic.reccontrol, "running_pid", return_value=None):
+                result = diagnostic.finish(log_path=log)
+            self.assertEqual(result.game, "Satisfactory")
+            self.assertEqual(result.summary.samples, 3)
+            self.assertEqual(result.findings, fake)
+            # peak GPU temp captured in the window, GPU-lost event recorded
+            self.assertEqual(result.summary.maxima["gpu.temp"][0], 81.0)
+            self.assertTrue(any(kind == "gpu-lost" for _ts, kind, _d in result.summary.events))
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,63 @@
+"""Tests for M6 runtime tunables (parse, command builders, value validation)."""
+
+import unittest
+from unittest import mock
+
+from rigdoctor.core import fixes
+from rigdoctor.core.fixes import Tunable
+
+
+class ParseTests(unittest.TestCase):
+    def test_bracketed(self):
+        self.assertEqual(fixes._bracketed("always [madvise] never"), (["always", "madvise", "never"], "madvise"))
+
+    def test_bracketed_none_active(self):
+        self.assertEqual(fixes._bracketed("a b c"), (["a", "b", "c"], None))
+
+
+class CommandBuilderTests(unittest.TestCase):
+    def test_governor_cmd_writes_value_to_sysfs(self):
+        cmd = fixes._cpu_governor_cmd("performance")
+        self.assertEqual(cmd[:2], ["/bin/sh", "-c"])
+        self.assertIn("performance", cmd[2])
+        self.assertIn("scaling_governor", cmd[2])
+
+    def test_persistence_cmd(self):
+        self.assertEqual(fixes._nvidia_persistence_cmd("Enabled"), ["nvidia-smi", "-pm", "1"])
+        self.assertEqual(fixes._nvidia_persistence_cmd("Disabled"), ["nvidia-smi", "-pm", "0"])
+
+    def test_swappiness_cmd_targets_procfs(self):
+        self.assertIn("/proc/sys/vm/swappiness", fixes._swappiness_cmd("10")[2])
+
+    def test_quoting_is_safe(self):
+        # A value that would be dangerous unquoted stays a single quoted token.
+        cmd = fixes._pcie_aspm_cmd("performance; rm -rf /")
+        self.assertIn("'performance; rm -rf /'", cmd[2])
+
+
+class ApplyValidationTests(unittest.TestCase):
+    def test_unknown_fix_returns_none(self):
+        self.assertIsNone(fixes.apply_command("does_not_exist", "x"))
+
+    def test_value_validated_against_live_options(self):
+        fake = Tunable("x", "X", ["a", "b"], "a")
+        with mock.patch.dict(fixes._TUNABLES, {"x": (lambda: fake, lambda v: ["echo", v])}, clear=False):
+            self.assertEqual(fixes.apply_command("x", "a"), ["echo", "a"])
+            self.assertIsNone(fixes.apply_command("x", "not-an-option"))
+
+    def test_apply_unknown_is_error(self):
+        rc, _ = fixes.apply("nope", "x")
+        self.assertEqual(rc, 1)
+
+
+class GameenvWiringTests(unittest.TestCase):
+    def test_findings_reference_known_fix_ids(self):
+        from rigdoctor.core import gameenv
+
+        fix_ids = {f.fix for f in gameenv.run_gameenv_checks() if f.fix}
+        # Whatever fixes the live system surfaces, each must be a real tunable id.
+        self.assertTrue(fix_ids.issubset(set(fixes._TUNABLES)))
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,73 @@
+"""Tests for M6 gaming-environment checks (pure evaluators + aggregate smoke test)."""
+
+import unittest
+
+from rigdoctor.core import gameenv
+from rigdoctor.core.health import Finding
+
+
+class AspmTests(unittest.TestCase):
+    def test_powersave_is_warning(self):
+        f = gameenv.evaluate_aspm("[powersave] performance powersupersave\n")
+        self.assertEqual(f.severity, "warning")
+        self.assertEqual(f.category, "PCIe")
+
+    def test_performance_is_ok(self):
+        self.assertEqual(gameenv.evaluate_aspm("[performance] powersave powersupersave").severity, "ok")
+
+    def test_default_is_info(self):
+        self.assertEqual(gameenv.evaluate_aspm("[default] performance powersave").severity, "info")
+
+    def test_missing_is_none(self):
+        self.assertIsNone(gameenv.evaluate_aspm(None))
+        self.assertIsNone(gameenv.evaluate_aspm("no brackets here"))
+
+
+class GovernorTests(unittest.TestCase):
+    def test_performance_only_is_ok(self):
+        self.assertEqual(gameenv.evaluate_governor({"performance"}).severity, "ok")
+
+    def test_powersave_is_warning(self):
+        f = gameenv.evaluate_governor({"powersave"})
+        self.assertEqual(f.severity, "warning")
+        self.assertEqual(f.fix, "cpu_governor")  # offers the live Apply dropdown
+
+    def test_dynamic_is_info(self):
+        self.assertEqual(gameenv.evaluate_governor({"schedutil"}).severity, "info")
+
+    def test_empty_is_none(self):
+        self.assertIsNone(gameenv.evaluate_governor(set()))
+
+
+class SwappinessTests(unittest.TestCase):
+    def test_high_is_info_with_suggestion(self):
+        f = gameenv.evaluate_swappiness(60)
+        self.assertEqual(f.severity, "info")
+        self.assertEqual(f.fix, "swappiness")  # offers the live Apply dropdown
+
+    def test_low_is_ok(self):
+        self.assertEqual(gameenv.evaluate_swappiness(10).severity, "ok")
+
+
+class ShaderCacheTests(unittest.TestCase):
+    def test_disabled_nvidia_is_warning(self):
+        self.assertEqual(gameenv.evaluate_shader_cache({"__GL_SHADER_DISK_CACHE": "0"}).severity, "warning")
+
+    def test_disabled_mesa_is_warning(self):
+        self.assertEqual(gameenv.evaluate_shader_cache({"MESA_SHADER_CACHE_DISABLE": "true"}).severity, "warning")
+
+    def test_default_is_ok(self):
+        self.assertEqual(gameenv.evaluate_shader_cache({}).severity, "ok")
+
+
+class AggregateTests(unittest.TestCase):
+    def test_run_returns_sorted_findings(self):
+        findings = gameenv.run_gameenv_checks()
+        self.assertTrue(all(isinstance(f, Finding) for f in findings))
+        order = {"critical": 0, "warning": 1, "info": 2, "ok": 3}
+        sevs = [order.get(f.severity, 9) for f in findings]
+        self.assertEqual(sevs, sorted(sevs))  # worst-first
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -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()
@@ -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()
@@ -0,0 +1,30 @@
+"""Tests for the M5 system inventory (render + dict round-trip; collect on real system)."""
+
+import unittest
+
+from rigdoctor.core import inventory
+from rigdoctor.core.inventory import Section
+
+
+class InventoryTests(unittest.TestCase):
+    def test_collect_returns_sections(self):
+        sections = inventory.collect()
+        self.assertTrue(sections)
+        titles = {s.title for s in sections}
+        self.assertIn("System", titles)
+        self.assertIn("CPU", titles)
+
+    def test_dict_round_trip(self):
+        sections = [Section("System", [("Kernel", "7.0.0"), ("Distro", "Ubuntu")])]
+        restored = inventory.from_dict(inventory.to_dict(sections))
+        self.assertEqual(restored[0].title, "System")
+        self.assertEqual(restored[0].items, [("Kernel", "7.0.0"), ("Distro", "Ubuntu")])
+
+    def test_render_markdown(self):
+        md = inventory.render_markdown([Section("CPU", [("Model", "Test CPU")])])
+        self.assertIn("## CPU", md)
+        self.assertIn("- **Model:** Test CPU", md)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,27 @@
+"""Tests for the host PTY session (M12 Tier 3)."""
+
+import time
+import unittest
+
+from rigdoctor.core.pty_session import PtySession
+
+
+class PtySessionTests(unittest.TestCase):
+    def test_runs_command_and_reads_output(self):
+        pty = PtySession(rows=24, cols=80)
+        try:
+            time.sleep(0.4)
+            pty.read()  # drain the shell prompt
+            pty.write(b"echo PTY_MARKER_42\n")
+            deadline = time.time() + 3
+            buf = ""
+            while time.time() < deadline and "PTY_MARKER_42" not in buf:
+                time.sleep(0.1)
+                buf += pty.read().decode(errors="replace")
+            self.assertIn("PTY_MARKER_42", buf)
+        finally:
+            pty.close()
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,38 @@
+"""Tests for M12 relay frames + guest HTML rendering (host/guest data shapes)."""
+
+import json
+import unittest
+
+from rigdoctor.core import share
+from rigdoctor.core.sampler import Sampler
+from rigdoctor.core.sources import available_sources
+
+
+class RelayFrameTests(unittest.TestCase):
+    def setUp(self):
+        self.sampler = Sampler(available_sources())
+
+    def test_full_frame_shape(self):
+        frame = json.loads(share.host_full_frame(self.sampler))
+        self.assertEqual(frame["type"], "full")
+        self.assertIn("groups", frame["snapshot"])
+        self.assertIsInstance(frame["report"], list)
+        self.assertIsInstance(frame["inventory"], dict)
+
+    def test_snapshot_frame_shape(self):
+        frame = json.loads(share.host_snapshot_frame(self.sampler))
+        self.assertEqual(frame["type"], "snapshot")
+        self.assertIn("groups", frame["snapshot"])
+
+    def test_guest_html_renders(self):
+        snap = {"groups": {"gpu": [{"name": "temp", "value": 51.0, "unit": "°C"}]}}
+        report = [{"severity": "ok", "category": "Logs", "title": "No errors"}]
+        inv = {"System": {"Kernel": "7.0.0"}}
+        html = share.guest_html(snap, report, inv)
+        self.assertIn("51.0 °C", html)
+        self.assertIn("No errors", html)
+        self.assertIn("Kernel", html)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,46 @@
+"""Tests for M12 Tier 2 share server: token gating + endpoints."""
+
+import json
+import threading
+import unittest
+import urllib.error
+import urllib.request
+
+from rigdoctor.core import share
+
+
+class ShareServerTests(unittest.TestCase):
+    def setUp(self):
+        self.srv, self.token = share.make_server("127.0.0.1", 0)
+        self.port = self.srv.server_address[1]
+        self.thread = threading.Thread(target=self.srv.serve_forever, daemon=True)
+        self.thread.start()
+
+    def tearDown(self):
+        self.srv.shutdown()
+
+    def _url(self, path, token=None):
+        q = f"?t={token}" if token else ""
+        return f"http://127.0.0.1:{self.port}{path}{q}"
+
+    def test_requires_token(self):
+        with self.assertRaises(urllib.error.HTTPError) as cm:
+            urllib.request.urlopen(self._url("/api/snapshot"), timeout=10)
+        self.assertEqual(cm.exception.code, 403)
+
+    def test_bad_token_rejected(self):
+        with self.assertRaises(urllib.error.HTTPError) as cm:
+            urllib.request.urlopen(self._url("/api/snapshot", "wrong"), timeout=10)
+        self.assertEqual(cm.exception.code, 403)
+
+    def test_snapshot_with_token(self):
+        data = json.load(urllib.request.urlopen(self._url("/api/snapshot", self.token), timeout=10))
+        self.assertIn("groups", data)
+
+    def test_page_served(self):
+        body = urllib.request.urlopen(self._url("/", self.token), timeout=10).read()
+        self.assertIn(b"read-only share", body)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,147 @@
+"""Tests for M6 Steam library & game detection (VDF parse, scan, tool filter, cache diff)."""
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from rigdoctor.core import steam
+
+_GAME_ACF = """"AppState"
+{{
+\t"appid"\t\t"{appid}"
+\t"name"\t\t"{name}"
+\t"installdir"\t\t"{installdir}"
+\t"SizeOnDisk"\t\t"{size}"
+\t"LastUpdated"\t\t"{updated}"
+}}
+"""
+
+_LIBRARYFOLDERS = """"libraryfolders"
+{{
+\t"0"
+\t{{
+\t\t"path"\t\t"{path}"
+\t\t"label"\t\t"Main"
+\t\t"apps"
+\t\t{{
+\t\t\t"570"\t\t"123"
+\t\t}}
+\t}}
+}}
+"""
+
+
+def _make_library(root: Path, games) -> Path:
+    """games: list of (appid, name, installdir, size, updated). Returns the library path."""
+    steamapps = root / "steamapps"
+    steamapps.mkdir(parents=True, exist_ok=True)
+    for appid, name, installdir, size, updated in games:
+        (steamapps / f"appmanifest_{appid}.acf").write_text(
+            _GAME_ACF.format(appid=appid, name=name, installdir=installdir, size=size, updated=updated)
+        )
+    return root
+
+
+class VdfTests(unittest.TestCase):
+    def test_parse_nested_and_pairs(self):
+        data = steam._parse_vdf(_GAME_ACF.format(
+            appid="570", name="Dota 2", installdir="dota 2 beta", size="15", updated="1700"))
+        state = data["AppState"]
+        self.assertEqual(state["appid"], "570")
+        self.assertEqual(state["name"], "Dota 2")
+        self.assertEqual(state["installdir"], "dota 2 beta")
+
+    def test_parse_handles_quotes_in_names(self):
+        acf = _GAME_ACF.format(appid="1", name="Baldur\\'s Gate 3", installdir="bg3", size="1", updated="1")
+        data = steam._parse_vdf(acf)
+        self.assertIn("Baldur", data["AppState"]["name"])
+
+    def test_parse_garbage_returns_empty(self):
+        self.assertEqual(steam._parse_vdf("not vdf at all"), {})
+
+
+class ToolFilterTests(unittest.TestCase):
+    def test_known_tool_appid(self):
+        self.assertTrue(steam.is_tool("228980", "Steamworks Common Redistributables"))
+
+    def test_proton_name_prefix(self):
+        self.assertTrue(steam.is_tool("9999999", "Proton 8.0"))
+        self.assertTrue(steam.is_tool("9999998", "Steam Linux Runtime 3.0 (sniper)"))
+
+    def test_real_game_is_not_a_tool(self):
+        self.assertFalse(steam.is_tool("570", "Dota 2"))
+
+
+class ScanTests(unittest.TestCase):
+    def test_scan_library_filters_tools(self):
+        with tempfile.TemporaryDirectory() as d:
+            lib = _make_library(Path(d), [
+                ("570", "Dota 2", "dota 2 beta", "15000000000", "1700000000"),
+                ("228980", "Steamworks Common Redistributables", "Steamworks Shared", "0", "0"),
+                ("1493710", "Proton Experimental", "Proton - Experimental", "0", "0"),
+            ])
+            games = steam.scan_library(str(lib))
+            names = {g.name for g in games}
+            self.assertEqual(names, {"Dota 2"})
+            self.assertEqual(games[0].size_bytes, 15000000000)
+
+    def test_scan_games_dedupes_and_sorts(self):
+        with tempfile.TemporaryDirectory() as d1, tempfile.TemporaryDirectory() as d2:
+            a = _make_library(Path(d1), [("10", "Zeta", "zeta", "1", "1"), ("20", "Alpha", "alpha", "1", "1")])
+            b = _make_library(Path(d2), [("20", "Alpha", "alpha", "1", "1")])  # dup appid 20
+            games = steam.scan_games([str(a), str(b)])
+            self.assertEqual([g.name for g in games], ["Alpha", "Zeta"])  # sorted, deduped
+
+
+class DiscoverTests(unittest.TestCase):
+    def test_discover_reads_libraryfolders(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = Path(d) / "Steam"
+            (root / "steamapps").mkdir(parents=True)
+            extra = Path(d) / "Extra"
+            (extra / "steamapps").mkdir(parents=True)
+            (root / "steamapps" / "libraryfolders.vdf").write_text(
+                _LIBRARYFOLDERS.format(path=str(extra)))
+            with mock.patch.object(steam, "steam_roots", return_value=[root]):
+                libs = steam.discover_libraries()
+            paths = {lib.path for lib in libs}
+            self.assertIn(str(root.resolve()), paths)   # root itself
+            self.assertIn(str(extra.resolve()), paths)  # the configured extra library
+
+
+class CacheDiffTests(unittest.TestCase):
+    def _rescan(self, lib, games_file, cfg):
+        with mock.patch.object(steam, "GAMES_FILE", games_file):
+            return steam.rescan(cfg=cfg)
+
+    def test_first_scan_has_no_new_then_added_game_is_new(self):
+        with tempfile.TemporaryDirectory() as d:
+            lib = _make_library(Path(d) / "lib", [("10", "Alpha", "alpha", "1", "1")])
+            games_file = Path(d) / "games.json"
+            cfg = {"steam_libraries": [str(lib)]}
+
+            first = self._rescan(lib, games_file, cfg)
+            self.assertEqual(first.new_appids, [])  # first run flags nothing as new
+
+            # Install a second game; it should be flagged new on the next scan.
+            _make_library(lib, [("10", "Alpha", "alpha", "1", "1"), ("20", "Beta", "beta", "1", "1")])
+            second = self._rescan(lib, games_file, cfg)
+            self.assertEqual(second.new_appids, ["20"])
+            self.assertEqual({g.name for g in second.games}, {"Alpha", "Beta"})
+
+    def test_acknowledge_clears_new(self):
+        with tempfile.TemporaryDirectory() as d:
+            lib = _make_library(Path(d) / "lib", [("10", "Alpha", "alpha", "1", "1")])
+            games_file = Path(d) / "games.json"
+            cfg = {"steam_libraries": [str(lib)]}
+            self._rescan(lib, games_file, cfg)
+            _make_library(lib, [("10", "Alpha", "alpha", "1", "1"), ("20", "Beta", "beta", "1", "1")])
+            self._rescan(lib, games_file, cfg)
+            with mock.patch.object(steam, "GAMES_FILE", games_file):
+                steam.acknowledge_new()
+                self.assertEqual(steam.load_cache()["new_appids"], [])
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -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()