From c200075b834a276dcfe3c66cf713ffb7ea3a42bf Mon Sep 17 00:00:00 2001
From: giovannino <git@cervelloelettrico.it>
Date: Tue, 21 Jul 2026 02:11:49 +0200
Subject: [PATCH] Update README.md

---
 README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)

diff --git a/README.md b/README.md
index 9cba605..af4c587 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,99 @@
 # server-monitor-dash
 
+A case-mounted touchscreen monitoring dashboard for self-hosted AI/inference
+servers, built with [Textual](https://textual.textualize.io/). CPU, GPU, and
+memory telemetry rendered "supercar dash" style — dense, glanceable, colour
+thresholded — rather than a plain systems-monitoring readout.
+
+Runs directly under a TTY autologin session. No X, no display server, and no
+GPU vendor lock-in for the interface itself (though GPU telemetry currently
+assumes `nvidia-smi` — see **Status** below).
+
+---
+
+## Why
+
+Most server monitoring tools are built for a terminal you're SSH'd into, not
+a small screen physically mounted in a case that someone actually looks at.
+This project is the opposite bet: build something that's genuinely nice to
+glance at from across a room, on a 5" panel, on hardware that's otherwise
+running unattended.
+
+## Features
+
+- **Live telemetry**: per-core CPU utilization, memory usage, GPU
+  temperature/utilization/power/fan speed
+- **Threshold-driven colour** (green → amber → red) on key gauges, rather
+  than flat, undifferentiated numbers
+- **Rolling history sparkline** for GPU temperature trend
+- **Idle-blank behaviour**: screen goes solid black after 15 minutes with no
+  touch/key input, to protect the physical panel from always-on burn-in over
+  years of continuous operation — any input wakes it immediately
+- **Tabbed layout**: Dashboard (functional), Request Assistance and Switch to
+  X (stubs — see Roadmap)
+
+## Requirements
+
+- Python 3.9+
+- [Textual](https://textual.textualize.io/) (`pip install textual
+  --break-system-packages`, or via `pipx`)
+- `nvidia-smi` on `PATH` for GPU telemetry (CPU/memory panels work without
+  it — GPU panel degrades gracefully to zero rather than crashing if
+  `nvidia-smi` is unavailable or fails)
+
+## Running
+
+```bash
+python3 server_dash.py
+```
+
+Intended to run under a dedicated, unprivileged monitoring user's autologin
+TTY session — not as root, and not as the account used for anything else on
+the box.
+
+## Status
+
+This is an early, working prototype — the CPU/memory/GPU telemetry panel is
+functional and tested; the two additional tabs are placeholders, not yet
+implemented:
+
+| Tab | Status |
+|---|---|
+| Dashboard | Working — live CPU/mem/GPU telemetry |
+| Request Assistance | Stub — will send a scripted notification email |
+| Switch to X | Stub — will invoke a narrowly-scoped, sudoers-gated VT switch to a separate login, for on-demand GPU tuning access via a real X session |
+
+Not yet fully compliant with CE OS script conventions (no test gates, no
+cleanup trap) — this is explicitly a prototype for iterating the interface
+design, not a hardened production deployment. See the script's own header
+comment for current detail.
+
+## Design notes
+
+- **GPU vendor**: currently NVIDIA-only via `nvidia-smi`. AMD/Intel GPU
+  support would need an equivalent backend behind the same `read_gpu_stats()`
+  interface — contributions welcome.
+- **Colour thresholds** (`TEMP_THRESHOLDS`, `UTIL_THRESHOLDS` in-script) are
+  currently fixed defaults, not yet configurable per-deployment. Worth
+  externalizing to a config file if this is deployed across multiple
+  machines with different thermal profiles.
+- **No hard dependency on a specific display size** — built for a 5"
+  case-mounted touchscreen, but Textual's layout should adapt reasonably to
+  other terminal sizes; untested on anything else so far.
+
+## Roadmap
+
+- [ ] Wire up Request Assistance (scripted outbound email, hostname in body)
+- [ ] Wire up Switch to X (sudoers-scoped `chvt` wrapper, see script comment)
+- [ ] Externalize colour thresholds to a config file
+- [ ] Bring up to full CE OS script compliance (test gates, cleanup trap)
+- [ ] Consider a non-NVIDIA GPU backend
+
+## License
+
+See [LICENSE](./LICENSE).
+
+---
+
+*Built standing on the shoulders of billions of dwarves.*
+*Created by John A. Hoeven with the ethical assistance of Claude AI.*