From 7697c7dc2be0df13bad30290d4098121c600f708 Mon Sep 17 00:00:00 2001
From: jasonwitty <jasonpwitty@proton.me>
Date: Sun, 24 Aug 2025 17:56:22 -0700
Subject: [PATCH] docs: add per-crate README.md and link via Cargo.toml readme
 field

---
 socktop/Cargo.toml       |  1 +
 socktop/README.md        | 26 ++++++++++++++++++++++++++
 socktop_agent/Cargo.toml |  1 +
 socktop_agent/README.md  | 32 ++++++++++++++++++++++++++++++++
 4 files changed, 60 insertions(+)
 create mode 100644 socktop/README.md
 create mode 100644 socktop_agent/README.md

diff --git a/socktop/Cargo.toml b/socktop/Cargo.toml
index 8faa99d..89a61a8 100644
--- a/socktop/Cargo.toml
+++ b/socktop/Cargo.toml
@@ -5,6 +5,7 @@ authors = ["Jason Witty <jasonpwitty+socktop@proton.me>"]
 description = "Remote system monitor over WebSocket, TUI like top"
 edition = "2021"
 license = "MIT"
+readme = "README.md"
 
 [dependencies]
 tokio = { workspace = true }
diff --git a/socktop/README.md b/socktop/README.md
new file mode 100644
index 0000000..15195dc
--- /dev/null
+++ b/socktop/README.md
@@ -0,0 +1,26 @@
+# socktop (client)
+
+Minimal TUI client for the socktop remote monitoring agent.
+
+Features:
+- Connects to a socktop_agent over WebSocket / secure WebSocket
+- Displays CPU, memory, swap, disks, network, processes, (optional) GPU metrics
+- Self‑signed TLS cert pinning via --tls-ca
+- Profile management with saved intervals
+- Low CPU usage (request-driven updates)
+
+Quick start:
+```
+cargo install socktop
+socktop ws://HOST:3000/ws
+```
+With TLS (copy agent cert first):
+```
+socktop --tls-ca cert.pem wss://HOST:8443/ws
+```
+Demo mode (spawns a local agent automatically on first run prompt):
+```
+socktop --demo
+```
+Full documentation, screenshots, and advanced usage:
+https://github.com/jasonwitty/socktop
diff --git a/socktop_agent/Cargo.toml b/socktop_agent/Cargo.toml
index 509b1b5..79adaf1 100644
--- a/socktop_agent/Cargo.toml
+++ b/socktop_agent/Cargo.toml
@@ -5,6 +5,7 @@ authors = ["Jason Witty <jasonpwitty+socktop@proton.me>"]
 description = "Remote system monitor over WebSocket, TUI like top"
 edition = "2021"
 license = "MIT"
+readme = "README.md"
 
 [dependencies]
 tokio = { version = "1", features = ["full"] }
diff --git a/socktop_agent/README.md b/socktop_agent/README.md
new file mode 100644
index 0000000..ad53a80
--- /dev/null
+++ b/socktop_agent/README.md
@@ -0,0 +1,32 @@
+# socktop_agent (server)
+
+Lightweight on‑demand metrics WebSocket server for the socktop TUI.
+
+Highlights:
+- Collects system metrics only when requested (keeps idle CPU <1%)
+- Optional TLS (self‑signed cert auto‑generated & pinned by client)
+- JSON for fast metrics / disks; protobuf (optionally gzipped) for processes
+- Accurate per‑process CPU% on Linux via /proc jiffies delta
+- Optional GPU & temperature metrics (disable via env vars)
+- Simple token auth (?token=...) support
+
+Run (no TLS):
+```
+cargo install socktop_agent
+socktop_agent --port 3000
+```
+Enable TLS:
+```
+SOCKTOP_ENABLE_SSL=1 socktop_agent --port 8443
+# cert/key stored under $XDG_DATA_HOME/socktop_agent/tls
+```
+Environment toggles:
+- SOCKTOP_AGENT_GPU=0      (disable GPU collection)
+- SOCKTOP_AGENT_TEMP=0     (disable temperature)
+- SOCKTOP_TOKEN=secret     (require token param from client)
+- SOCKTOP_AGENT_METRICS_TTL_MS=250 (cache fast metrics window)
+- SOCKTOP_AGENT_PROCESSES_TTL_MS=1000
+- SOCKTOP_AGENT_DISKS_TTL_MS=1000
+
+Systemd unit example & full docs:
+https://github.com/jasonwitty/socktop