From e683691a53715dd46b448dd5f053bd8a980b898c Mon Sep 17 00:00:00 2001
From: c4ch3c4d3 <23181631+c4ch3c4d3@users.noreply.github.com>
Date: Mon, 24 Aug 2026 10:00:44 -0600
Subject: [PATCH] docs: spec for dashboard RAM usage card

---
 .../specs/2026-08-24-ram-usage-card-design.md | 59 +++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 docs/specs/2026-08-24-ram-usage-card-design.md

diff --git a/docs/specs/2026-08-24-ram-usage-card-design.md b/docs/specs/2026-08-24-ram-usage-card-design.md
new file mode 100644
index 0000000..1d04b72
--- /dev/null
+++ b/docs/specs/2026-08-24-ram-usage-card-design.md
@@ -0,0 +1,59 @@
+# Dashboard RAM Usage Card — Design Record
+
+- **Date:** 2026-08-24
+- **Status:** Approved (design review), implementation pending
+- **Scope:** Mark VIII WebUI dashboard — add a RAM Usage status card between
+  Disk Usage and Uptime, showing memory used / total in the same format as the
+  Disk Usage card.
+
+## 1. Goal
+
+The dashboard (`/` → Dashboard) currently shows status cards for Clients
+Connected, Handshakes Captured, Disk Usage, and Uptime. Add a RAM Usage card
+positioned after Disk Usage and before Uptime, displaying `used / total` (e.g.
+`120 MB / 256 MB`) to match the Disk Usage card's presentation. The Pager is a
+`ramips/mt76x8` device with 256 MB RAM.
+
+## 2. Data source
+
+The device's memory stats come from `/proc/meminfo` (available locally, since
+the webui server runs on the Pager):
+
+- `MemTotal` — total RAM in kB
+- `MemAvailable` — available RAM in kB (falls back to `MemFree`)
+
+`used = MemTotal - MemAvailable`, matching how `free` reports usage on OpenWRT.
+
+The health check already parses this file via `_mem_percent()` (`server.py`)
+but only exposes a percentage. The status endpoint has no memory field today.
+
+## 3. Changes
+
+### Backend — `payload/user/remote_access/pager-webui/server.py`
+
+- Add `mem_data()`: parse `/proc/meminfo`, return
+  `{'size': total_bytes, 'used': used_bytes, 'avail': avail_bytes}` — the same
+  shape as `disk_data()` (which returns `{size, used, avail}` in bytes).
+  Return `{}` on parse failure, consistent with `disk_data()`.
+- Wire into `status_data()` as `'mem': mem_data()`.
+
+### Frontend — `payload/user/remote_access/pager-webui/www/js/views.js`
+
+- Add `['mem', 'RAM Usage']` to the card `defs` array between
+  `['disk', 'Disk Usage']` and `['uptime', 'Uptime']` (dashboard view).
+- In the status `update()` handler, render
+  `fmtBytes(s.mem.used) + ' / ' + fmtBytes(s.mem.size)`; on missing data show
+  `Unavailable`; in the initial-load catch path set `—`, mirroring the disk
+  card's error handling.
+
+### Tests — `tests/test_status.py`
+
+- Add `mem_data()` parse test using a temp fake `/proc/meminfo` file
+  (the function takes an optional path argument, like `battery_data(base)`).
+- Add `mem` to the `h_status` payload-shape key assertion.
+
+## 4. Non-goals
+
+- No memory graph/history — the Clients chart stays as is.
+- No RAM percentage formatting on the card.
+- No changes to the `/api/health` `mem_percent` metric.