Release 0.0.2: M3 logger (CLI + GUI), GUI-first, CI release workflow

Crash-capture logger (M3):
- crash-safe JSONL (fsync per sample), size-based rotation, GPU-lost/recovered
  markers, atomic status file
- CLI: record run/start/stop/status/report (run = systemd-ready entrypoint)
- shared core.reccontrol so CLI + GUI drive the same recorder
- crashlog tests (writer, rotation, reader, summary, recorder)

GUI:
- Recording/Logs page: start/stop/interval controls, live status, post-crash report
- shared render helpers (format_raw/headline, render_summary)

Docs/decisions:
- GUI-first (D17); CLI keeps full parity
- D8 revised: user-local self-updating install primary, .deb optional
- planned: M12 session sharing (D16), M13 no-root auto-update from public repo (D18)
- versioning + CHANGELOG convention (D19)

Infra:
- .gitea/workflows/release.yml: build wheel+sdist and publish a Gitea release
  v<version> on push to main
- align version to the 0.0.x release line; bump to 0.0.2

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

docs/ARCHITECTURE.md

@@ -129,8 +129,9 @@ as a single callable so all three front-ends share one implementation.
    optionally **enable** the `systemd --user` logger service and choose its trigger mode (D6).
 5. **Verify** each installed module's `probe()` and print a readiness summary.
 
-Module list/bundling is final (D14). Packaging is `.deb`-first (D8); the wizard layers
-module selection on top of the package.
+Module list/bundling is final (D14). Packaging: a **user-local install is primary**
+(self-updating from the public repo, no root — D8/D18), with an **optional `.deb`** system
+package; the wizard layers module selection on top of either.
 
 ## 9. GPU vendor abstraction
 | Capability | NVIDIA (first) | AMD (later) | Intel (later) |

docs/DECISIONS.md

@@ -1,8 +1,9 @@
 # RigDoctor — Decisions & Open Questions
 
 Format: each item is **OPEN** (needs a call) or **DECIDED** (with date + rationale).
-Decisions D1–D15 were all settled on 2026-05-21; the original open questions are kept below
-with their resolutions so the reasoning is traceable. No tracked decisions are currently open.
+Decisions D1–D19 are settled (D1–D15 on 2026-05-21); the original open questions are kept
+below with their resolutions so the reasoning is traceable. No tracked decisions are
+currently open.
 
 ## Decided
 
@@ -34,9 +35,10 @@ AMD and Intel come later behind the vendor abstraction; nothing should hard-code
 way that blocks them.
 
 ### D5 — MVP scope — *DECIDED 2026-05-21*
-**M1 + M3 + M4 (the *Essential* bundle), NVIDIA-only**, CLI-first. This is the first build
-target — it captures the seed crash and explains the logs before any installer, GUI, tray,
-or multi-vendor work.
+**M1 + M3 + M4 (the *Essential* bundle), NVIDIA-only.** This was the first build target — it
+captures the seed crash and explains the logs before any installer, multi-vendor, etc. work.
+*(The MVP was built CLI-first; per D17 the GUI is now the primary interface going forward —
+the CLI keeps full parity.)*
 
 ### D6 — Crash-logger trigger model — *DECIDED 2026-05-21*
 **Let the user choose.** All three modes are supported and selectable (installer + config):
@@ -50,10 +52,13 @@ or multi-vendor work.
 generators. Users who want to reproduce load can run existing tools (gpu-burn, vkmark,
 stress-ng) themselves alongside the logger.
 
-### D8 — Distribution / packaging — *DECIDED 2026-05-21*
-**`.deb` package** as the primary distribution channel (matches the Ubuntu-first focus). The
-`.deb` declares dependencies per module group; the interactive installer (M9) handles module
-selection on top. AUR / Flatpak / COPR are possible later, not now.
+### D8 — Distribution / packaging — *DECIDED 2026-05-21; revised 2026-05-21 (see D18)*
+**Primary: a user-local install** (pipx/venv or a versioned bundle under `~/.local`, owned by
+the user) so the app can **self-update from the public Gitea releases with no root** (D18). A
+**`.deb` remains an optional** system-install channel for users who prefer it (updated via
+apt). *Why the revision:* the repo is public and we want frictionless, GUI-first self-updates,
+which a root-owned system package can't apply silently. The interactive installer (M9) layers
+module selection on top of either channel. AUR / Flatpak / COPR still later, if warranted.
 
 ### D9 — Scope of action (read-only vs apply-fixes) — *DECIDED 2026-05-21*
 **Read-only + suggestions.** RigDoctor diagnoses, monitors, and **suggests** actions in
@@ -118,10 +123,69 @@ build or maintain mappings for other package managers. A thin seam is left in th
 another package manager *could* be added later, but multi-distro support is **not** a planned
 deliverable. Revisit only if Ubuntu-only proves too narrow.
 
+### D16 — Session sharing / remote assist (M12) — *DECIDED 2026-05-21*
+Build a **session-sharing / remote-assist** capability (new module **M12**) so a user (A)
+can let a helper (B) inspect their machine. **Full ladder, built in order:**
+1. **Diagnostic bundle export** — `share export` packages inventory (M5) + recent capture
+   log (M3) + a report into one file A sends to B; B opens it in RigDoctor. One-way, no live
+   connection. Safest; build first.
+2. **Live read-only view** — a small local server serving the live dashboard + logs
+   read-only, reached over a **user-chosen tunnel** (Tailscale / cloudflared / SSH reverse
+   tunnel — *no RigDoctor-hosted relay*, to keep the no-telemetry promise). Token-gated,
+   short TTL, A approves and can kill instantly. No terminal.
+3. **Gated interactive terminal** — wrap an existing trusted tool (`tmate`/`sshx`) rather
+   than rolling our own; **read-only link by default**, read-write requires explicit
+   per-session consent. This is a deliberate, consent-gated exception to the read-only stance
+   (D9) — it's full machine access and must be treated as such.
+
+*Cross-cutting principles:* explicit per-session consent; ephemeral, revocable tokens;
+clear permission escalation (view ≠ shell); no mandatory central relay; session audit log.
+*Note:* this adds M12 on top of the "final" list from D14; the catalog is updated accordingly.
+
+### D17 — GUI-first interface emphasis — *DECIDED 2026-05-21*
+The **desktop GUI (M10) is the primary, default interface** for end users — it's the more
+user-friendly way in, and **every capability** (recording, reports, status, …) must be
+reachable from it. This **supersedes the earlier "CLI-first / terminal-first" framing**
+(updates D5 and the SPEC wording).
+- *The CLI is not removed:* it keeps **full functionality** for headless / SSH / server /
+  scripting use, and it's the engine the background daemon runs on.
+- *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*
+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.**
+- *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**
+  (`/api/v1/repos/jessey/rigdoctor/releases/latest`) over HTTPS; compare to the running version.
+- *Apply:* download the new release bundle, **verify checksum/signature**, stage it
+  (e.g. `~/.local/share/rigdoctor/versions/x.y.z`), swap a symlink atomically, then restart
+  (including the `systemd --user` daemon).
+- *GUI-first (D17):* a non-intrusive "update available" prompt + one-click apply; `rigdoctor
+  update` in the CLI.
+- *Security:* HTTPS only; verify checksum/signature before swapping; never run unverified code.
+- *Privacy (no telemetry):* version-check only — no tracking; auto-check is opt-out-able.
+- *`.deb` users:* the optional `.deb` channel updates via apt instead; auto-update targets the
+  user-local install.
+- *Caveat (to confirm before building):* the Gitea instance currently **requires sign-in for
+  API calls** (`"Only signed in user is allowed to call APIs."`), so anonymous version checks
+  need the instance/repo set to allow anonymous access — or a separate public version endpoint
+  (e.g. a static file or a mirror).
+
+### D19 — Versioning & changelog — *DECIDED 2026-05-21*
+**Track a version number on every change.** SemVer-style `MAJOR.MINOR.PATCH` (pre-1.0: bump
+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
+follow the released **0.0.x** line — first release was **V0.0.1**; current is **0.0.2**.
+
 ## Open
 
-None currently — all tracked decisions (D1–D15) are resolved. New questions will be added
+None currently — all tracked decisions (D1–D19) 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 proposed list) and per-module apt package names (filled in as modules land).
+set (D13), per-module apt package names, M12's tunnel/token specifics, and M13's
+update mechanism (APT repo vs. self-installed `.deb`).
 </content>
 </invoke>

docs/MODULES.md

@@ -2,14 +2,14 @@
 
 Status: ⬜ not started · 🟦 designing · 🟨 in progress · ✅ done
 
-> Final module set (D14). **M7 (stress/repro) was dropped (D7).** M10/M11 are the GUI and
-> tray modules (D10/D11). GPU scope reads "all (NVIDIA first)" — NVIDIA is implemented first,
-> others via the vendor abstraction (D4).
+> Module set per D14, plus **M12 (session sharing, D16)** and **M13 (auto-update, D18)**.
+> **M7 (stress/repro) was dropped (D7).** M10/M11 are the GUI and tray modules (D10/D11).
+> GPU scope reads "all (NVIDIA first)" — NVIDIA first, others via the vendor abstraction (D4).
 
 | ID | Module | Bundle | Key deps | GPU scope | Priority | Status |
 |----|--------|--------|----------|-----------|----------|--------|
 | M1 | Sensor core | Essential | none (nvidia-smi, sysfs) | all (NVIDIA first) | P0 | ⬜ |
-| M3 | Crash-capture logger | Essential | none (opt: smartmontools) | 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 | ⬜ |
 | M2 | Live monitor (TUI) | Monitoring | none (stdlib curses) | all | P1 | ⬜ |
 | M8 | Alerting | Monitoring | libnotify (opt) | all | P2 | ⬜ |
@@ -18,6 +18,8 @@ Status: ⬜ not started · 🟦 designing · 🟨 in progress · ✅ done
 | 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 | ⬜ |
 | ~~M7~~ | ~~Stress / repro~~ | — | — | — | — | ❌ dropped (D7) |
 
 ## Notes per module
@@ -26,6 +28,11 @@ Status: ⬜ not started · 🟦 designing · 🟨 in progress · ✅ done
 - **M3 Crash-capture logger** — the highest-value piece for the seed use case. `fsync` per
   sample; GPU-lost detection via query timeout; bounded rotation; `systemd --user` service
   with a **user-selectable trigger mode** (always-on / game-launch / manual — D6).
+  *Implemented (manual trigger):* JSONL log with fsync-per-sample, size-based rotation
+  (`log_max_bytes`/`log_backups`), GPU-lost/recovered event markers, atomic status file, and
+  `rigdoctor record run|start|stop|status|report`. The foreground `run` is the systemd-ready
+  entrypoint; the service unit + always-on/game-launch triggers (D6/D12) land in Phase 4.
+  Also fully driven from the GUI's Recording/Logs page (M10) via shared `core.reccontrol`.
 - **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 →
@@ -37,20 +44,33 @@ Status: ⬜ not started · 🟦 designing · 🟨 in progress · ✅ done
 - **M10 Desktop GUI** — PySide6 graphical front-end over the core engine (dashboard, log
   browser, report viewer, logger controls). Optional; adds the Qt dependency. *Bootstrapped
   early (ahead of its Phase 4 slot) at the user's request:* dark-themed window with sidebar
-  nav and a live dashboard (circular gauges + collapsible per-subsystem cards, temperature-
-  colored values); Logs/Health/Inventory are placeholders until M3–M5.
+  nav, a live dashboard (circular gauges + collapsible per-subsystem cards, temperature-
+  colored values), and a **Recording/Logs page** with full M3 controls (start/stop/status +
+  post-crash report). Health/Inventory remain placeholders until M4/M5. GUI-first per D17.
 - **M11 Tray applet** — `QSystemTrayIcon` menu-bar applet. Dropdown shows live M1 readouts
   (CPU temp, GPU temp, memory used/total, status dot) and is led by a **Run Diagnostic**
   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.
+- **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
+  **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
+  update via apt instead.)
 
 ## Bundles (final — D14)
 - **Essential:** M1 + M3 + M4  *(the MVP, NVIDIA-only — D5)*
 - **Monitoring:** M2 + M8
 - **Diagnostics:** M5 + M6
 - **Desktop UI:** M10 + M11  *(adds PySide6)*
+- **Sharing:** M12  *(session sharing / remote assist — D16)*
 
 ## MVP candidate — *confirmed (D5)*
 **M1 + M3 + M4 (Essential), NVIDIA-only, CLI-first.** Gives a working tool that captures the

docs/ROADMAP.md

@@ -11,13 +11,13 @@ Ubuntu + NVIDIA first; `.deb` distribution (see `DECISIONS.md`).
 - [x] Lock the MVP scope (M1 + M3 + M4, NVIDIA-only)
 
 ## Phase 1 — MVP: capture *this* crash  (Essential bundle, NVIDIA-only, CLI)
-- [ ] M1 sensor core (NVIDIA via nvidia-smi + hwmon for CPU/RAM/NVMe), stdlib-only
-- [ ] M3 crash-capture logger (CSV, fsync per sample, GPU-lost detection, rotation,
-      `systemd --user` service)
-- [ ] Manual trigger mode first (`rigdoctor record start/stop`); other modes in Phase 4
+- [x] M1 sensor core (NVIDIA via nvidia-smi + hwmon for CPU/RAM/NVMe), stdlib-only
+- [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)
-- [ ] `--report` post-crash summary (max temps/power, throttle events, last N samples)
+- [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.
 
@@ -46,9 +46,20 @@ Ubuntu + NVIDIA first; `.deb` distribution (see `DECISIONS.md`).
 ## 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)
 
+## 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.
+
 > **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.
 

docs/SPEC.md

@@ -31,8 +31,9 @@ RigDoctor's crash-safe logger is designed to fix exactly that.
 - Catch and preserve the machine's state in the seconds before a hard freeze.
 - Make hard-to-investigate gaming faults debuggable: collect scattered signals, correlate
   them, and explain them.
-- Offer **three ways to run**: full **CLI / headless** (works over SSH), a **desktop GUI**,
-  and a **system-tray / top-menu-bar applet** with quick actions. (D10/D11)
+- Be **GUI-first** (D17): the **desktop GUI** is the primary interface, complemented by a
+  **system-tray / top-menu-bar applet** for quick actions — backed by a **full CLI** that
+  keeps complete functionality for headless / SSH / scripting use. (D10/D11/D17)
 - Be modular: a novice installs a one-click "monitor + capture + report" bundle; a power
   user installs everything including the GUI, tray, and diagnostics.
 - Low overhead; safe defaults; no telemetry/phone-home.
@@ -135,7 +136,18 @@ rather than adding a new one.
 Interactive wizard: detect GPU vendor (NVIDIA-first) → present module menu grouped into
 bundles with descriptions and the exact packages each needs → resolve & install (apt first)
 → write config → optionally enable the `systemd --user` logger service and pick its trigger
-mode. Delivered alongside the `.deb` (D8). Module list/bundling is final per D14.
+mode. Delivered with the user-local install (and the optional `.deb`) (D8). Module
+list/bundling is final per D14.
+
+### M12 — Session sharing / remote assist (D16)
+Lets a user (A) grant a helper (B) inspection access, as an escalating, consent-driven
+ladder: (1) **diagnostic bundle export** (inventory + recent capture log + report, one-way);
+(2) **live read-only view** of the dashboard + logs over a user-chosen tunnel
+(Tailscale/cloudflared/SSH — no RigDoctor-hosted relay); (3) **gated interactive terminal**
+wrapping an existing tool (tmate/sshx), read-only by default, read-write only on explicit
+consent. Per-session consent, ephemeral revocable tokens, permission escalation (view ≠
+shell), and a session audit log. Tier 3 is a deliberate, consent-gated exception to the
+read-only stance (D9). Built in Phase 6.
 
 ## 5. Non-functional requirements
 - **Zero hard deps for the core/CLI/daemon** — Python stdlib + tools already present. **Qt
@@ -144,8 +156,9 @@ mode. Delivered alongside the `.deb` (D8). Module list/bundling is final per D14
 - **Crash-safe logging** — flush + `fsync` per sample; bounded disk usage.
 - **Low overhead** — default ≤1 Hz sampling; negligible CPU/GPU cost. The always-on daemon
   is stdlib-only (no Qt loaded) so it stays tiny.
-- **Headless-equivalent** — every diagnostic capability is reachable from the CLI; the GUI
-  and tray are conveniences over the same engine, never the only way to do something.
+- **GUI-first, CLI-complete** (D17) — the GUI is the primary interface, but every capability
+  is *also* reachable from the CLI so RigDoctor runs fully headless (SSH/servers). Both
+  front-ends sit over the same engine; neither is the only way to do something.
 - **Privacy** — local only; inventory export is opt-in and reviewable; no telemetry.
 - **Portability** — graceful degradation when a sensor/tool is unavailable (N/A, not crash).