Initial commit: docs, decisions, and M1 sensor core

Planning docs (SPEC, ARCHITECTURE, MODULES, ROADMAP, DECISIONS) with
decisions D1-D15 settled: RigDoctor name, Python 3 + Qt/PySide6 stack
(core/CLI/daemon stdlib-only), Ubuntu + NVIDIA first, .deb packaging,
read-only + suggestions, GUI + tray modules, stress module dropped.

First code: the M1 sensor core (stdlib-only) and a CLI.
- core engine: Reading/Sample model, Sampler, hwmon reader
- self-probing sources (NVIDIA first): nvidia-smi GPU, coretemp/k10temp
  CPU, /proc/meminfo + DDR5 SPD memory, NVMe storage
- CLI: snapshot (text/JSON), monitor, sources; record/report stubbed
- stdlib unittest smoke tests

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

README.md

@@ -0,0 +1,83 @@
+# RigDoctor
+
+A **modular diagnostics, monitoring, and health-check toolkit for Linux gamers.**
+
+> **Status:** 🟢 Phase 1 (MVP) in progress. Foundational decisions are settled and the
+> **sensor core (M1)** works — `snapshot` / `monitor` read NVIDIA GPU, CPU, memory, and
+> NVMe live. Crash logger (M3) and health report (M4) are next. See `docs/ROADMAP.md`.
+
+## Why this exists
+
+Linux gaming hardware faults are hard to diagnose: GPUs falling off the PCIe bus, the screen
+suddenly going black mid-game, silent thermal/VRAM throttling, power transients,
+driver/library mismatches, Proton quirks, and CPU governor / power-profile misconfiguration.
+The data needed to diagnose them is scattered across `nvidia-smi`, `/sys/class/hwmon`,
+`journalctl`, SMART, and more — and the most useful readings (the ones right before a hard
+freeze) are usually lost because nothing flushed them to disk.
+
+RigDoctor pulls all of that into one modular tool: live monitoring, crash-safe logging, a
+one-shot health report, and an interactive installer that only sets up the modules a given
+user actually needs for their hardware.
+
+**Seed use cases:** an RTX 3070 that intermittently "falls off the bus" under heavy GPU load
+(Path of Exile on Linux, Escape from Tarkov on Windows), and a monitor going black mid-game.
+See `docs/SPEC.md` §1.
+
+## How you run it
+
+Three front-ends over one shared engine — pick what fits:
+- **CLI / headless** — full functionality from the terminal, works over SSH.
+- **Desktop GUI** — graphical dashboard, log browser, and health-report viewer.
+- **Tray applet** — a small applet in the top menu bar with quick actions (e.g. start
+  recording) and at-a-glance status.
+
+The GUI and tray are optional modules; a headless install loses no diagnostic capability.
+
+## Key decisions (settled)
+
+| Topic | Decision |
+|-------|----------|
+| Name | **RigDoctor** |
+| Language / stack | **Python 3 + Qt (PySide6)** — core/CLI/daemon stdlib-only; Qt only for GUI/tray |
+| Primary distro | **Ubuntu** (Debian via apt); others best-effort later |
+| Primary GPU | **NVIDIA** first; AMD, then Intel later |
+| MVP | **Sensor core + crash logger + health report** (NVIDIA-only, CLI-first) |
+| Distribution | **`.deb`** + interactive module installer |
+| Scope of action | **Read-only + suggestions** (no auto-apply yet) |
+| Stress tests | **Out of scope** |
+
+Full rationale and the still-open questions are in `docs/DECISIONS.md`.
+
+## Repo layout
+
+| Path | Purpose |
+|------|---------|
+| `docs/SPEC.md` | Product specification — vision, requirements, modules (the main planning doc) |
+| `docs/ARCHITECTURE.md` | Technical design — core engine, front-ends, daemon, installer |
+| `docs/MODULES.md` | Catalog of modules with scope, dependencies, status |
+| `docs/ROADMAP.md` | Phased milestones |
+| `docs/DECISIONS.md` | Decision log + remaining open questions |
+| `src/rigdoctor/` | Source code — `core/` engine + sources, `cli.py`, `render.py` |
+| `installer/` | Installer / `.deb` packaging (empty until Phase 4) |
+| `tests/` | Tests (stdlib `unittest`) |
+
+## Run it (dev)
+
+Stdlib-only, no install needed (target is Python ≥ 3.11; tested on 3.14):
+
+```bash
+PYTHONPATH=src python3 -m rigdoctor snapshot     # one-shot sensor read
+PYTHONPATH=src python3 -m rigdoctor snapshot --json
+PYTHONPATH=src python3 -m rigdoctor monitor -n 1 # live view (Ctrl-C to quit)
+PYTHONPATH=src python3 -m rigdoctor sources       # list detected sensor sources
+PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+Or `pip install -e .` to get a `rigdoctor` command on your PATH.
+
+## Start here
+
+1. Read `docs/SPEC.md` for what we're building.
+2. Read `docs/ROADMAP.md` for the build order (Phase 1 = the MVP).
+3. Read `docs/DECISIONS.md` for the settled decisions (D1–D15).
+</content>