pyre-cli 10.0.0 → 10.2.0

package/README.md

@@ -1,585 +1,286 @@
-# pyre
-
-Cross-platform system monitoring CLI for **macOS**, **Linux**, and **Windows**: temps, CPU, memory, disk, battery, GPU, power draw, live dashboard, packet monitor, process management, export, alerts, P2P live data streaming, web dashboard, SSH monitoring, micro-benchmarking, and background service management.
-
-![Version](https://img.shields.io/badge/version-5.0.0-blue)
-![macOS](https://img.shields.io/badge/macOS-14%2B-lightgrey)
-![Linux](https://img.shields.io/badge/Linux-x86__64%20%7C%20arm64-orange)
-![Windows](https://img.shields.io/badge/Windows-10%20%7C%2011%20%7C%20Server-blue)
-![Node](https://img.shields.io/badge/node-18%2B-green)
-![License](https://img.shields.io/badge/license-MIT-green)
-
-> **Note:** things may not work as intended if your firewall settings do not allow inbound connections for P2P streaming or Web dashboard mode.
->
-> You can skip init with Enter, but you may encounter some UI bugs. This is being worked on.
-
-## Features
-
-- **P2P live data streaming** — send live system stats to another system over TCP with password authentication, TLS encryption, rate limiting, IP allow/deny lists, audit logging, and HMAC message signing
-- **Real-time system stats & per-core CPU** — CPU brand, cores, frequency, load, per-core utilization mini-bars, and overall usage
-- **GPU monitoring** — GPU model, VRAM, utilization, temperature, and process count (detailed mode)
-- **Power draw monitoring** — CPU watts, GPU watts, and combined power draw via SMC/ioreg
-- **Memory monitoring & pressure** — usage, swap, wired, compressed, purgeable, swapins/outs, and kernel VM pressure level
-- **Disk I/O throughput & space** — read/write speed per volume and mounted volume space usage
-- **Battery & power health** — level, power source, condition, charge cycles, max capacity, health trends, estimated time to empty, discharge rate, power draw in watts
-- **Packet monitor** — network packet counts, packet rates, active TCP connections, top network processes
-- **Advanced network monitoring** — real-time bandwidth rates (RX/TX bytes/sec), protocol breakdown (TCP/UDP), connection state analysis (ESTABLISHED, LISTENING, TIME_WAIT, CLOSE_WAIT), listening port detection, top remote hosts, per-process network I/O tracking, and GlassWire-style modern TUI panel with sparkline graphs
-- **Task list** — running tasks/applications sorted by CPU with PID, user, memory, state, and runtime
-- **Thermal state** — CPU temperature via `pmset` and `powermetrics` (sudo for detailed readings)
-- **Network** — RX/TX bytes and per-second rates
-- **Top processes & search-as-you-type** — live filtering, tree view, sorting by CPU/memory/PID, and process kill with protected PID confirmation guard
-- **Interactive live dashboard** — full-screen TUI with keyboard-driven controls, mouse support, configurable panel layout, and tab-based panel navigation
-- **Snapshot export** — JSON, CSV, TSV, HTML, or Markdown output formats
-- **Continuous CSV logging & Anomaly Digest** — automatic per-tick logging and statistical spike analysis (`pyre anomalies`)
-- **Blender render tracking** — automatically detects running Blender background renders, tracks elapsed time, frame progress, completion percentage, render engine, and blend file; fully loggable via CSV/JSON/Markdown exports
-- **Visual themes & custom themes** — six built-in color themes plus user-defined JSON theme support in `~/.config/pyre/themes/`
-- **Persistent configuration & Profiles** — save themes and thresholds in `~/.config/pyre/config.json`, plus atomic profile management (`pyre profile`)
-- **Alert system & webhooks** — configurable threshold alerts with terminal bell, desktop notifications, webhook POST payload execution (`--webhook-url`), and custom shell command execution (`--alert-cmd`)
-- **System diagnostic tool (`pyre doctor`)** — check permissions, SMC access, Gatekeeper, SIP status, XProtect definitions, and P2P reachability
-- **Security & Ecosystem inspectors** — System Extensions inspector (`pyre extensions`), Homebrew health (`pyre brew`), and Time Machine backup status
-- **Accessible plain-text mode** — `--plain`/`--a11y` mode for screen readers and ANSI-free logging
-- **Grafana Integration** — ready-to-import Grafana dashboard template (`grafana/pyre-dashboard.json`)
-- **History & Snapshot Diff** — query historical CSV log trends (`pyre history`) and compare snapshot files side-by-side (`pyre diff`)
-- **Multi-host fleet dashboard** — stream and tile stats from multiple remote Macs (`pyre fleet`)
-- **Menu Bar & xbar integration** — generate menu bar plugin script (`pyre xbar`) for continuous background status display
-- **Graph mode toggle** — switch between sparkline and bar graph rendering in the live dashboard
-- **P2P dashboard panel** — monitor P2P server status and peer events directly from the live dashboard
-- **Temperature unit toggle** — switch between Celsius and Fahrenheit display in live mode
-- **Hardware & Displays overview** — `pyre info` prints hardware, connected displays, and Time Machine status
-- **Remote SSH monitoring** — `pyre ssh <host>` streams a remote Mac's live dashboard locally
-- **Web dashboard** — `pyre web` serves an auto-refreshing HTML dashboard with real-time SSE stream on a local port
-- **Micro-benchmarking & Energy Cost** — `pyre bench <cmd>` logs resource usage and estimates energy consumption/cost (kWh)
-- **Update checker** — `pyre update` checks npm registry for new pyre-cli releases
-
-## Installation
-
-### npm (macOS, Linux, Windows)
+<p align="center">
+  <a href="https://github.com/somalip/pyre">
+    <img src="assets/icon.svg" width="96" height="96" alt="Pyre Icon" />
+  </a>
+</p>
+
+<h1 align="center">pyre</h1>
+
+<p align="center">
+  <b>Cross-platform system telemetry and diagnostics suite for macOS, Linux, and Windows.</b><br />
+  Hardware-level performance metrics, interactive TUI, web dashboards, encrypted P2P mesh, and native macOS window.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/pyre-cli"><img src="https://img.shields.io/npm/v/pyre-cli.svg?style=flat" alt="npm version" /></a>
+  <a href="package.json"><img src="https://img.shields.io/badge/version-10.1.0-blue?style=flat" alt="Version" /></a>
+  <a href="#requirements"><img src="https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=flat" alt="Platforms" /></a>
+  <a href="#requirements"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-green?style=flat" alt="Node" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat" alt="License" /></a>
+</p>
+
+<p align="center">
+  <a href="#quick-install">Quick Install</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#interactive-tui">Interactive TUI</a> •
+  <a href="#highlights">Highlights</a> •
+  <a href="#native-ui-and-web-dashboard">Native UI &amp; Web</a> •
+  <a href="#comparison">Comparison</a> •
+  <a href="#keybindings">Keybindings</a> •
+  <a href="#cli-reference">CLI Reference</a>
+</p>
+
+<br />
+
+<p align="center">
+  <img src="assets/pyre-tui.svg" alt="Pyre Terminal User Interface" width="100%" />
+</p>
 
-```bash
-npm install -g pyre-cli
-```
+---
 
-### curl (macOS & Linux)
+## Quick Install
 
 ```bash
+# macOS / Linux (curl)
 curl -fsSL https://raw.githubusercontent.com/somalip/pyre/main/install.sh | bash
-```
 
-### PowerShell (Windows)
+# Homebrew (macOS)
+brew install somalip/pyre/pyre
 
-```powershell
+# Windows (PowerShell)
 irm https://raw.githubusercontent.com/somalip/pyre/main/install.ps1 | iex
+
+# npm (Global)
+npm install -g pyre-cli
 ```
 
+---
+
 ## Quick Start
 
 ```bash
-pyre                           # Static snapshot, all system stats
-pyre --detailed                # Include sensor / powermetrics detail
-pyre --json                    # JSON output (also --csv, --tsv, --html, --md)
-pyre --plain                   # Plain-text accessible output without ANSI noise
-
-pyre live                      # Interactive live dashboard
-pyre live --interval 3 --log   # Custom refresh interval + auto-logging
-pyre live --alert-cpu 80 --alert-temp 85 --temp-unit f
-
-pyre ui                        # Launch native macOS UI dashboard
-pyre web                       # Serve auto-refreshing live web portal on localhost
-
-pyre anomalies --since 7d      # Statistical resource spike digest from past CSV logs
-pyre doctor                    # System diagnostics (Gatekeeper, SIP, XProtect, powermetrics)
-pyre extensions                # System extensions inspector (systemextensionsctl)
-pyre brew                      # Homebrew health summary & cellar size
-pyre update                    # Check for pyre-cli updates
-pyre profile save dev          # Save active configuration profile
-pyre profile load dev          # Load configuration profile
-pyre info                      # Concise hardware, display & Time Machine overview
-pyre bench "make build"        # Benchmark command & estimate kWh energy cost
-pyre benchmark                 # Run a 1-minute CPU benchmark calculating digits of PI
-```
+# Interactive live TUI dashboard with real-time graphs and telemetry
+pyre live
 
-## Options Reference
+# One-shot instant health summary in plain English
+pyre check
 
-These options apply to both static snapshots and `pyre live`, except where noted.
+# Launch the native macOS Activity Monitor window
+pyre ui
 
-| Option | Description |
-|---|---|
-| `-j, --json` | Output as JSON |
-| `--html` | Output as self-contained HTML |
-| `--md` | Output as Markdown |
-| `-c, --csv` | Output as CSV |
-| `-t, --tsv` | Output as TSV |
-| `--plain` / `--a11y` | Plain text output mode without ANSI colors or line-drawing characters |
-| `--detailed` | Include detailed system info and sensor readings |
-| `--since <range>` | Time range for anomaly digest (e.g. `1d`, `7d`, `yesterday`) |
-| `--theme <name>` | Theme for live mode (`default`, `dracula`, `cyberpunk`, `monochrome`, `nord`, `gruvbox`) |
-| `--interval <seconds>` | Refresh interval for live mode (default: `2`) |
-| `--once` | Show a single static snapshot instead of live feed |
-| `--out <file>` | Write snapshot output to a file |
-| `--export-dir <dir>` | Directory for live-mode snapshot exports and logs (default: `./pyre-exports`) |
-| `--log` | Start continuous CSV logging immediately when live mode starts |
-| `--tree` | Show process tree view instead of flat list |
-| `--sort <key>` | Sort processes by: `cpu`, `mem`, `pid`, `user`, `command`, `state`, `threads`, `runtime` |
-| `--limit <n>` | Max processes in snapshot (`0` = all, default: `10`) |
-| `--alert-cpu <pct>` | CPU usage alert threshold (default: `90`) |
-| `--alert-temp <c>` | CPU temperature alert threshold in Celsius (default: `95`) |
-| `--temp-unit <unit>` | Temperature display unit: `c` or `f` (default: `c`) |
-| `--webhook-url <url>` | URL to POST payload to when an alert threshold is triggered |
-| `--alert-cmd <cmd>` | Shell command to execute when an alert threshold is triggered |
-| `--port <port>` | Port number for web server mode (default: `3000`) |
-
-## Commands
-
-### Static snapshot & diagnostics
-
-| Command | Description |
-|---|---|
-| `pyre` | Show all system stats in a formatted table |
-| `pyre --once` | Show a single static snapshot (same as default without live) |
-| `pyre --json` | JSON output |
-| `pyre --html` | Self-contained HTML report |
-| `pyre --md` | Markdown tables |
-| `pyre doctor` | Run system diagnostics (permissions, Gatekeeper, SIP, XProtect, P2P network) |
-| `pyre extensions` | System Extensions inspector (`systemextensionsctl list`) |
-| `pyre brew` | Homebrew health panel (installed formulae, outdated count, Cellar disk size, doctor summary) |
-| `pyre blender` | Track active Blender background renders: PID, blend file, engine, frame progress, elapsed time, and completion status |
-| `pyre update` | Check npm registry for latest `pyre-cli` release |
-| `pyre profile <save\|load\|list> [name]` | Atomic configuration profile management (`~/.config/pyre/profiles/`) |
-| `pyre config <show\|reset>` | View or reset persistent configuration file (`~/.config/pyre/config.json`) |
-| `pyre completions <zsh\|bash\|fish>` | Generate shell auto-completion scripts |
-
-### Hardware overview & history
-
-| Command | Description |
-|---|---|
-| `pyre info` | Concise hardware summary (CPU, memory pressure, GPU, battery, displays, Time Machine) |
-| `pyre anomalies [--since N]` | Compute z-score anomalies and print plain-language resource spike digest |
-| `pyre history [--days N]` | Graph historical resource trends from CSV logs over past N days |
-| `pyre diff <file1.json> <file2.json>` | Compare two saved snapshot files side-by-side |
+# Serve a real-time web portal with Server-Sent Events (SSE)
+pyre web
 
-### Benchmarking & Menu Bar
+# Run statistical z-score anomaly detection over historical telemetry
+pyre anomalies --since 7d
 
-| Command | Description |
-|---|---|
-| `pyre bench <cmd>` | Log CPU, memory, network, power draw, and estimate kWh energy cost during command execution |
-| `pyre benchmark` | Run a 1-minute CPU benchmark calculating digits of PI and score the system |
-| `pyre xbar` | Generate an xbar / SwiftBar menu bar plugin script for stats display |
+# Benchmark a command execution and compute real kWh energy cost
+pyre bench "npm run build"
 
-### Remote & Multi-host monitoring
+# Audit system permissions, sensors, SIP, and diagnostic health
+pyre doctor
+```
 
-| Command | Description |
-|---|---|
-| `pyre ssh <host>` | Stream live stats from a remote Mac over SSH |
-| `pyre fleet <host1> [host2]...` | Multi-host live dashboard monitoring multiple Macs simultaneously |
+---
 
-### Live dashboard
+## Interactive TUI
 
-| Command | Description |
-|---|---|
-| `pyre live` | Start the interactive live dashboard |
+Launch with `pyre live` for a responsive, full-terminal dashboard featuring:
 
-### Web & Native dashboards
+- **Live Sparklines and Histograms**: Real-time 60-second rolling charts for CPU, memory, thermals, and network throughput.
+- **Apple Silicon Cluster Telemetry**: Granular Performance (P-Core) and Efficiency (E-Core) usage, GPU cores, and Apple Neural Engine (ANE) load.
+- **Process Management**: Search-as-you-type fuzzy filtering (`/`), instant tree view hierarchy (`t`), and custom signal dispatch (`k`, `S`).
+- **Visual Customizer (`c`)**: Switch on the fly between 6 built-in themes (`default`, `dracula`, `cyberpunk`, `monochrome`, `nord`, `gruvbox`) or create custom color maps.
+- **Continuous Logging (`l`)**: Seamlessly log rolling telemetry directly to CSV files for replay and historical analysis.
 
-| Command | Description |
-|---|---|
-| `pyre web` | Serve an auto-refreshing live web portal with real-time SSE stats streaming on localhost (`--port <port>`) |
-| `pyre ui` | Launch the native macOS UI dashboard (wraps the web portal in a native window) |
+---
 
-### P2P
+## Highlights
 
-| Command | Description |
+| Capability | Description |
 |---|---|
-| `pyre server` | Detect the local IP and print ready-to-paste commands for starting a P2P server and connecting a client on the same LAN (default port `9876`, default password `mysecret`) |
-| `pyre p2p server` | Start a P2P server that streams live stats to authenticated peers |
-| `pyre p2p connect` | Connect to a P2P server and display live stats |
-
-See [P2P Live Data Streaming](#p2p-live-data-streaming) below for the full option set.
+| **Deep Hardware Probes** | Granular Apple Silicon P/E cluster utilization, SMC thermals, per-core CPU breakdown, GPU VRAM, battery cycle health, and real-time power draw in watts. |
+| **Interactive TUI & Themes** | Rolling sparklines, process trees, full mouse navigation, and 6 built-in color schemes with custom panel configuration. |
+| **Native macOS App Mode** | High-performance native macOS liquid-glass dashboard window (`pyre ui`) with draggable frames, widget mode (`--compact`), and floating window support (`--ontop`). |
+| **Live Web Portal** | Zero-latency browser dashboard (`pyre web`) powered by Server-Sent Events (SSE), Chart.js visualizers, and responsive dark theme. |
+| **Encrypted P2P Streaming** | Directly stream live telemetry across nodes over TCP with TLS encryption, SHA-256 handshake challenge-response, and HMAC-SHA256 message signing. |
+| **Fleet & SSH Aggregation** | Monitor remote nodes over SSH (`pyre ssh <host>`) or aggregate hundreds of servers into an auto-tiled overview (`pyre fleet`). |
+| **Socket & Packet Forensics** | Track socket connection states (`ESTABLISHED`, `LISTENING`, `TIME_WAIT`), top remote hosts, and per-process network bandwidth. |
+| **AI Anomaly Explanation** | Explain performance spikes and thermal throttles in plain English using local Ollama models or OpenAI (`pyre explain`). |
+| **Multi-Format Export** | Export instant snapshots to JSON, CSV, TSV, HTML, or Markdown reports, plus an importable Grafana dashboard template. |
 
 ---
 
-## P2P Live Data Streaming
+## Native UI and Web Dashboard
 
-Send live system stats to another system over a TCP connection with password authentication. The server streams `StatsData` snapshots to authenticated peers at the configured interval. You can also start or stop the P2P server from the live dashboard by pressing `r`.
+### Native macOS Window (`pyre ui`)
 
-### Server options
+Run Pyre as a standalone macOS desktop application without third-party heavyweight runtimes:
 
 ```bash
-pyre p2p server --p2p-host 0.0.0.0 --p2p-port 9876 --p2p-password mysecret
-```
+# Standard floating window
+pyre ui
 
-| Option | Description |
-|---|---|
-| `--p2p-host <host>` | Bind address (default: `0.0.0.0`) |
-| `--p2p-port <port>` | Port number (default: `9876`) |
-| `--p2p-password <password>` | Password for authentication (required) |
-| `--interval <seconds>` | Data refresh interval (default: `2`) |
-| `--detailed` | Include detailed sensor readings |
-| `--p2p-cert <file>` | TLS certificate file (PEM) for encrypted connections |
-| `--p2p-key <file>` | TLS private key file (PEM) for the server |
-| `--p2p-ca <file>` | TLS CA certificate file (PEM) — required by clients using `--p2p-tls` |
-| `--p2p-rate-limit <n>` | Max auth attempts per IP per minute (default: `5`) |
-| `--p2p-allow <ips>` | Comma-separated list of allowed IPs (empty = all) |
-| `--p2p-deny <ips>` | Comma-separated list of denied IPs |
-| `--p2p-audit-log <dir>` | Directory for P2P audit logs |
-| `--p2p-hmac-key <key>` | HMAC key for message signing (default: derived from password) |
-
-### Client options
+# Compact desktop widget mode pinned always on top
+pyre ui --compact --ontop
 
-```bash
-pyre p2p connect --p2p-host <server-ip> --p2p-port 9876 --p2p-password mysecret
+# Expose web endpoint to local network alongside native window
+pyre ui --lan --port 8080
 ```
 
-| Option | Description |
-|---|---|
-| `--p2p-host <host>` | Server address (default: `127.0.0.1`) |
-| `--p2p-port <port>` | Server port (default: `9876`) |
-| `--p2p-password <password>` | Password for authentication (required) |
-| `--p2p-tls` | Enable TLS encryption for the connection |
-| `--p2p-ca <file>` | TLS CA certificate file (PEM) — required when using `--p2p-tls` |
-| `--p2p-insecure` | Skip TLS certificate verification (client only) |
-| `--p2p-audit-log <dir>` | Directory for P2P client audit logs |
-| `--p2p-hmac-key <key>` | HMAC key for message signing (must match server) |
+### Browser Web Dashboard (`pyre web`)
 
-### Security features
-
-- **TLS encryption** — pass `--p2p-cert`/`--p2p-key`/`--p2p-ca` on the server and `--p2p-tls --p2p-ca` on the client for encrypted connections.
-- **Rate limiting** — `--p2p-rate-limit <n>` caps authentication attempts per IP per minute to deter brute-force attacks.
-- **IP allow/deny lists** — `--p2p-allow` restricts connections to specific IPs; `--p2p-deny` blocks specific IPs while allowing all others.
-- **Audit logging** — `--p2p-audit-log <dir>` logs connects, auth successes/failures, disconnects, rate-limit hits, and IP blocks.
-- **HMAC message signing** — every message is signed with HMAC-SHA256. The key derives from the password by default, or set `--p2p-hmac-key` explicitly for rotation or interoperability (must match on both sides).
-
-### Same local network (LAN) setup
-
-Both machines must be on the same local network (same Wi-Fi or wired subnet). The server listens on `0.0.0.0` (all interfaces) by default, so any device on the LAN can reach it as long as the port is open.
-
-On the **server machine**, find its local IP address:
+Serve a browser dashboard accessible anywhere on your network:
 
 ```bash
-hostname -I
-# or
-ifconfig | grep "inet " | grep -v 127.0.0
-```
-
-Use that IP (e.g. `192.168.1.25`) in the client command:
+# Start local web dashboard
+pyre web --port 3000
 
-```bash
-pyre p2p connect --p2p-host 192.168.1.25 --p2p-port 9876 --p2p-password mysecret
+# Broadcast over local area network with access PIN
+pyre web --lan --port 3000
 ```
 
-**Troubleshooting**
-
-- If the client can't reach the server, confirm both machines are on the same subnet (ping the server IP from the client).
-- Verify the port is open (no local firewall blocking TCP `9876`).
-- Never expose the server directly to the public internet; it's designed for LAN use only.
-
-### Protocol
-
-Length-prefixed JSON over TCP, with HMAC-SHA256 signing on every message:
-
-1. Client connects to the server.
-2. Server sends a `challenge` message with a random nonce.
-3. Client responds with an `auth` message containing the SHA-256 hash of `password:nonce`.
-4. Server validates the hash and responds with `auth-ok` or `auth-fail`.
-5. Once authenticated, the server streams `data` messages containing `StatsData` snapshots at the configured interval.
-6. Both sides exchange `ping`/`pong` keepalives every 15 seconds.
-7. Either side can send a `disconnect` message to close gracefully.
-
-### Server controls
-
-While the server is running, type these on its stdin (or press `Ctrl+C`):
-
-| Command | Action |
-|---|---|
-| `status` | Print the number of currently connected peers |
-| `q` / `quit` / `exit` | Shut down the server gracefully |
-
-### Client controls
-
-While connected, the client displays live stats in a formatted table. Press `Ctrl+C` to disconnect. It reconnects automatically after 3 seconds if the connection drops.
-
 ---
 
-## Live Dashboard
-
-Run with `pyre live`.
-
-| Key | Action |
-|---|---|
-| `q` | Quit the dashboard |
-| `p` | Pause / resume the refresh cycle |
-| `d` | Toggle detailed sensor mode |
-| `g` | Show / hide sparkline graphs |
-| `b` | Cycle graph mode (sparkline ↔ bar) |
-| `s` | Cycle sort order (CPU → memory → PID → user → command → state → threads → runtime) |
-| `f` | Cycle export format (JSON → CSV → TSV → HTML → Markdown) |
-| `T` | Cycle temperature unit (Celsius ↔ Fahrenheit) |
-| `e` | Export a snapshot to the export directory |
-| `l` | Toggle continuous CSV logging |
-| `c` | Open the UI customizer |
-| `/` | Open process filter |
-| `k` | Open process kill (enter PID, then Enter to confirm) |
-| `S` | Open signal picker for kill (cycle SIGTERM → SIGKILL → SIGINT → SIGHUP → SIGSTOP → SIGCONT) |
-| `t` | Toggle process tree view |
-| `r` | Toggle P2P server (or enter P2P password input) |
-| `+` / `-` | Increase / decrease refresh interval by 1 second |
-| `←` / `→` / `Tab` | Cycle to previous / next panel tab |
-| `1`–`9`, `0` | Jump to panel by number (cpu, mem, gpu, power, battery, thermal, network, packets, tasks, disk) |
-| `P` | Toggle process panel |
-| `C` | Toggle containers panel |
-| `B` | Toggle Blender render tracker panel |
-| `Esc` | Close customizer or clear filter/kill input |
-
-### UI Customizer
-
-Press `c` to open the customizer overlay. From there:
-
-- Cycle through six built-in themes (Default, Dracula, Cyberpunk, Monochrome, Nord, Gruvbox) — `↑`/`↓` or `j`/`k` to navigate, `Enter`/`Space` to select
-- Toggle individual panels (CPU, Memory, GPU, Power, Battery, Thermal, Network, Packets, Tasks, Disk, Processes, Containers, Blender) on or off
-- Switch graph mode between sparkline and bar charts
-- Toggle process tree view
-- Toggle temperature unit between Celsius and Fahrenheit
-- Toggle notifications on or off
-
-### Mouse support
-
-- **Click tab bar** — click a panel tab (row 4) to jump directly to that panel
-- **Scroll** — scroll through process lists in panels with many entries
-- Enabled by default; disable with `mouseEnabled = false` in the customizer
+## Comparison
+
+| Feature | Pyre | btop | htop | Glances |
+|---|:---:|:---:|:---:|:---:|
+| **Interactive TUI & Sparklines** | Yes (6 themes + JSON) | Yes | Limited | Yes |
+| **Native macOS Desktop Window** | Yes (Swift Cocoa) | No | No | No |
+| **Apple Silicon P/E + GPU + ANE** | Yes (Granular watts) | Partial | Partial | Partial |
+| **Encrypted P2P Telemetry** | Yes (TLS + HMAC) | No | No | Partial (Plain) |
+| **Real-time Web Dashboard (SSE)** | Yes (Zero-config) | No | No | Yes |
+| **Multi-Host Fleet Aggregation** | Yes (SSH / P2P) | No | No | Yes (Web only) |
+| **Socket Connection Forensics** | Yes | Partial | No | Partial |
+| **Statistical Anomaly Radar** | Yes (Z-score) | No | No | No |
+| **Energy & Cost Profiler** | Yes (kWh / Joules) | No | No | No |
+| **System Security Doctor** | Yes (SIP / Sensors) | No | No | No |
+| **Export Formats** | JSON, CSV, TSV, HTML, MD | No | No | InfluxDB, CSV |
 
 ---
 
-## Process Management
+## Keybindings
 
-Available in the live dashboard (and partially in static snapshots via flags).
+Inside `pyre live`:
 
-### Sorting
-
-Press `s` to cycle through sort modes, or use `--sort <key>` in static snapshot mode (default: `cpu`):
-
-| Sort key | Description |
-|---|---|
-| `cpu` | Sort by CPU usage (descending) |
-| `mem` | Sort by memory usage (descending) |
-| `pid` | Sort by process ID |
-| `user` | Sort by username |
-| `command` | Sort by command name |
-| `state` | Sort by process state |
-| `threads` | Sort by thread count |
-| `runtime` | Sort by total runtime |
+### Navigation & Views
 
-### Filtering
+| Key | Action | Key | Action |
+|:---:|---|:---:|---|
+| `q` | Quit dashboard | `1`–`9` | Jump directly to panel tab |
+| `p` | Pause / resume live refresh | `←` / `→` | Switch active panel tab |
+| `g` | Toggle history graphs on / off | `+` / `-` | Increase / decrease refresh interval |
+| `b` | Cycle graph style (sparkline ↔ bar) | `d` | Toggle sensor detail expansion |
+| `c` | Open theme & panel customizer | `?` | Toggle keyboard shortcuts overlay |
 
-Press `/` to open a process filter and type a substring to narrow the list. Press `Esc` to clear it.
+### Processes & Actions
 
-### Tree view
+| Key | Action | Key | Action |
+|:---:|---|:---:|---|
+| `/` | Search & filter processes | `k` | Enter process kill mode (type PID) |
+| `t` | Toggle hierarchical tree view | `S` | Select termination signal (`SIGTERM`, `SIGKILL`) |
+| `s` | Cycle sort (`cpu`, `mem`, `pid`, `user`) | `l` | Toggle continuous CSV background logging |
+| `e` | Export snapshot (`json`, `csv`, `html`, `md`) | `r` | Start / stop P2P streaming server |
 
-Press `t` to toggle between a flat process list and a tree view showing parent/child relationships. In static snapshot mode, use `--tree`.
-
-### Killing processes
-
-Press `k` to enter kill mode: type the PID, then press `Enter` to send `SIGTERM` (default), or `Esc` to cancel.
-
-### Signal picker
-
-Press `S` to open the signal picker. Cycle with `↑`/`↓` or `j`/`k`, then `Enter` to send the selected signal to the PID entered in kill mode:
-
-| Signal | Description |
-|---|---|
-| `SIGTERM` | Graceful termination (default) |
-| `SIGKILL` | Force kill |
-| `SIGINT` | Interrupt (Ctrl+C equivalent) |
-| `SIGHUP` | Hangup |
-| `SIGSTOP` | Stop (pause) the process |
-| `SIGCONT` | Continue a stopped process |
+Mouse support: click any tab, button, or process row directly in the terminal, or scroll to browse processes.
 
 ---
 
-## Alerts & Notifications
+## CLI Reference
 
-The live dashboard monitors critical metrics and notifies you when thresholds are exceeded:
-
-| Metric | Default threshold | Alert behavior |
-|---|---|---|
-| CPU usage | 90% | Terminal bell (`\x07`) + red status message for 5 seconds + desktop notification |
-| CPU temperature | 95°C | Terminal bell + red status message for 5 seconds + desktop notification |
-
-Alerts fire once when a threshold is first crossed and reset when conditions clear. Thresholds are configurable via `--alert-cpu` and `--alert-temp`, or in the config file (`cpuAlertPct` and `tempAlertC` in `~/.config/pyre/config.json`).
-
-## Themes
-
-| Theme | Description |
-|---|---|
-| **default** | Muted greys and cyan accents; safe for any terminal |
-| **dracula** | The popular Dracula dark palette |
-| **cyberpunk** | High-contrast neon on black |
-| **monochrome** | White-only; useful for colour-blind users or terminals without 256-colour support |
-| **nord** | Arctic-inspired cool tones |
-| **gruvbox** | Retro warm palette |
+### Dashboards & Views
 
-Cycle themes with `c` in the customizer overlay, or set a default with `--theme <name>`.
+```bash
+pyre                            # Terminal snapshot
+pyre live                       # Interactive full-screen TUI
+pyre ui [--compact] [--ontop]   # Native macOS desktop window
+pyre web [--port 3000] [--lan]  # Browser portal with live SSE stream
+pyre fleet host1 host2 host3    # Unified multi-host fleet dashboard
+pyre ssh user@server            # Stream stats from remote machine over SSH
+```
 
-## Export Formats
+### Telemetry, Diagnostics & Benchmarks
 
-### Snapshot export
+```bash
+pyre check                      # One-line health summary
+pyre anomalies [--since 7d]     # Statistical z-score anomaly detector
+pyre doctor                     # Diagnostic audit of permissions, SIP, sensors
+pyre bench "<cmd>"              # Profile execution time, memory, and kWh energy
+pyre benchmark                  # 1-minute CPU benchmark scoring digits of PI
+pyre netusage [--top 15]        # Real-time per-process socket & bandwidth forensics
+pyre brew                       # Package manager health check & disk cache report
+pyre smart                      # S.M.A.R.T. disk health monitor & drive wear
+pyre blender                    # Background Blender 3D render job tracker
+pyre pipe                       # Continuous newline-delimited JSON stream
+```
 
-Triggered by the `e` key in live mode, or the `--out` flag. Written to the export directory (`./pyre-exports` by default):
+### Automation, Profiles & Daemon
 
-```
-pyre-2026-07-26T10-54-47-191Z.json
-pyre-2026-07-26T10-54-52-306Z.csv
-pyre-2026-07-26T10-54-52-306Z.html
-pyre-2026-07-26T10-54-52-306Z.md
+```bash
+pyre watchdog                   # Autonomous daemon monitoring rules & killing rogue procs
+pyre serve [--port 8080]        # Lightweight REST API server exposing JSON endpoints
+pyre profile save <name>        # Save active configuration profile
+pyre profile load <name>        # Restore saved profile
+pyre config show                # Display current settings (~/.config/pyre/config.json)
+pyre completions <zsh|bash>     # Generate shell auto-completions
 ```
 
-Format follows the current export format — cycle with `f` in live mode, or set via `--json`, `--csv`, `--tsv`, `--html`, `--md` in static mode.
-
-### Continuous CSV logging
+---
 
-Triggered by the `l` key in live mode, or the `--log` flag. Each tick appends a row to a timestamped file. Old logs are automatically rotated (max 20 files or 50 MB, files older than 7 days are pruned):
+## Encrypted P2P Streaming
 
-```
-pyre-log-2026-07-26T10-54-47-191Z.csv
-```
+Stream live system stats directly between hosts over TCP with mutual authentication:
 
-Row format:
+```bash
+# 1. On server machine (Host)
+pyre p2p server --p2p-password "secret-token" --p2p-port 9876
 
-```
-timestamp,cpu_usage,mem_usage_percent,temp_c,net_rx_bytes,net_tx_bytes,net_rx_packets,net_tx_packets,connections,thermal_state
+# 2. On client machine (Viewer)
+pyre p2p connect --p2p-host 192.168.1.50 --p2p-password "secret-token" --p2p-port 9876
 ```
 
-## Requirements
-
-- **Node.js 18+**
-- **macOS:** macOS 14+ (Sonoma or later recommended). Optional `sudo` for `powermetrics` detailed thermal/power readings.
-- **Linux:** Any modern Linux distribution (Ubuntu/Debian, Fedora/RHEL, Arch) with kernel 4.x+; reads `/proc` and `/sys`. Optional `smartmontools` for disk health.
-- **Windows:** Windows 10, Windows 11, or Windows Server 2016+ with PowerShell 5.1+.
+Security and networking capabilities:
+- **TLS Encryption**: Mutual authentication via `--p2p-tls --p2p-cert <file> --p2p-key <file>`
+- **Challenge Verification**: SHA-256 handshake challenge-response prevents replay attacks.
+- **Integrity Signing**: Cryptographic HMAC-SHA256 signatures validated on every packet payload.
+- **Access Control**: IP address whitelisting (`--p2p-allow <ips>`) and rate limiting (`--p2p-rate-limit <n>`).
 
-  On macOS, to enable password‑less access for `powermetrics` (optional, for detailed sensor readings), run:
+---
 
-  ```bash
-  echo "$(whoami) ALL=(root) NOPASSWD: /usr/bin/powermetrics" | sudo tee /etc/sudoers.d/pyre-powermetrics
-  ```
+## Requirements
 
-## Project Structure
+| Platform | Minimum Requirement | Notes |
+|---|---|---|
+| **Node.js** | 18.0.0 or higher | Recommended: Node 20 LTS |
+| **macOS** | macOS 14+ (Sonoma, Sequoia) | Full Apple Silicon (M1/M2/M3/M4) & Intel support |
+| **Linux** | Kernel 4.x+ | x86_64, arm64, aarch64 (`/proc` & `/sys`) |
+| **Windows** | Windows 10, 11, Server 2016+ | PowerShell 5.1+ or PowerShell Core 7+ |
 
-```
-pyre/
-├── src/
-│   ├── index.ts            # CLI entry point (commander definitions, main())
-│   ├── anomaliesCmd.ts     # Resource spike & anomaly digest generator
-│   ├── brewHealth.ts       # Package manager health inspector (Brew, APT, Pacman, DNF, Winget, Scoop)
-│   ├── doctor.ts           # System diagnostics (macOS SIP/Gatekeeper, Linux /proc/sys, Windows WMI)
-│   ├── extensions.ts       # Extensions/modules inspector (macOS extensions, Linux lsmod, Windows driverquery)
-│   ├── service.ts          # Background service daemon manager (launchd, systemd, schtasks)
-│   ├── updateCheck.ts      # Passive and on-demand npm registry version check
-│   ├── monitors/           # System metric collection (CPU, memory, disk, battery, thermal, network, packets, power, tasks)
-│   │   ├── index.ts        # Public API: collectAll, collectPower, collectPackets, collectTasks
-│   │   ├── types.ts        # TypeScript interfaces for all metric types
-│   │   ├── smc.ts          # SMC sensor reading with caching (macOS)
-│   │   ├── collectors.ts   # Metric collection orchestrator & platform dispatch
-│   │   ├── platform/       # OS-specific native metric collectors
-│   │   │   ├── linux.ts    # Linux /proc, /sys, df, ps, and netstat collectors
-│   │   │   └── windows.ts  # Windows os, WMI/PowerShell, netstat, and tasklist collectors
-│   │   └── run.ts          # Shared shell & PowerShell execution helpers
-│   ├── formatters/         # Output formatting and rendering
-│   │   ├── index.ts        # Public API: formatTable, formatJson, formatCsv, formatTsv, formatGraphs
-│   │   ├── output.ts       # JSON/CSV/TSV serialisation and sparkline graphs
-│   │   ├── render.ts       # Dashboard table layout, cards, and panels
-│   │   ├── themes.ts       # Six built-in colour themes
-│   │   └── types.ts        # TableOptions, VisibleItems, ThemeName, and other public-facing type definitions
-│   ├── live/               # Interactive live dashboard
-│   │   ├── index.ts        # Public API: startLive, stopLive
-│   │   ├── state.ts        # Shared mutable session state
-│   │   ├── input.ts        # Keypress handling, signal picker, protected PID kill guards
-│   │   ├── render.ts       # Screen rendering and alert checking
-│   │   ├── export.ts       # Snapshot export and CSV logging
-│   │   └── types.ts        # LiveOptions, ExportFormat, InputMode, SortMode
-│   ├── p2p/                # P2P live data streaming (server + client)
-│   │   ├── index.ts        # Public API: P2PServer, P2PClient
-│   │   ├── types.ts        # P2P protocol type definitions
-│   │   ├── protocol.ts     # Length-prefixed JSON message framing
-│   │   ├── server.ts       # TCP server: auth, TLS, rate limiting, IP filtering, audit logging, HMAC signing, data streaming
-│   │   └── client.ts       # TCP client that connects and displays live data
-│   ├── state/              # Config & profile state management
-│   │   └── config.ts       # Config file I/O & atomic profile save/load
-│   ├── history.ts          # Rolling history buffer for sparkline data
-│   ├── sparkline.ts        # ASCII sparkline rendering & plain-text mode
-│   └── utils/              # Shared utility functions
-├── dist/                   # Built output (esm)
-├── grafana/                # Grafana dashboard JSON template
-├── pyre-exports/           # Default directory for snapshot exports and logs
-├── Formula/                # Homebrew formula
-├── install.sh              # curl installation script
-├── package.json
-├── tsconfig.json
-└── README.md
-```
+---
 
 ## Development
 
-### Setup
-
 ```bash
+# 1. Clone repository
 git clone https://github.com/somalip/pyre.git
 cd pyre
-npm install
-```
-
-### Scripts
 
-| Script | Description |
-|---|---|
-| `npm run build` | Compile TypeScript to ESM via tsup, output to `dist/` |
-| `npm start` | Run the built binary from `dist/` |
-| `npm run dev` | Run directly via `tsx` (no build step) |
-| `npm test` | Verify the built binary responds to `--help` |
-
-## Roadmap
-
-Proposed features for upcoming versions, organized by effort and impact.
-
-### Tier 1 — High Impact, Achievable
-
-| Feature | Description |
-|---|---|
-| **AI Anomaly Explanation** (`pyre explain`) | Translate z-score spikes into plain-English diagnoses using a local (Ollama) or API-based LLM |
-| **S.M.A.R.T. Disk Health** (`pyre smart`) | Display SSD/HDD wear level, reallocated sectors, power-on hours, and remaining lifespan via `smartctl` |
-| **Docker / Container Panel** | Show running Docker/OrbStack containers with CPU%, memory, network I/O, and status — toggle with `C` in the live dashboard |
-| **Fan Speed Monitoring** | Display current RPM for all system fans via SMC readings in the Thermal panel |
-| **Log Replay Mode** (`pyre replay`) | Load a historical CSV log and play it back inside the interactive TUI with scrubbing controls |
-| **Multi-Channel Alert Integrations** | Native Slack, Discord, Pushover, and ntfy.sh alert targets with pre-configured payload templates (extends `--webhook-url`) |
-| **Prometheus Exporter** | Expose a `/metrics` endpoint in Prometheus text format — `src/prometheus.ts` is already stubbed |
-
-### Tier 2 — Strong Differentiation
+# 2. Install dependencies
+npm install
 
-| Feature | Description |
-|---|---|
-| **Plugin System** | User-authored metric collectors as JS scripts in `~/.config/pyre/plugins/` rendered as custom dashboard panels |
-| **Per-App Network Usage** (`pyre netusage`) | Real-time and cumulative network I/O broken down per application, backed by `nettop` (parser already in repo) |
-| **Configurable Dashboard Grid** | Define custom panel layout, order, and sizing in `~/.config/pyre/config.json` |
-| **Smart Battery Predictor** | Use accumulated power-drain history from CSV logs to produce a personalized, heuristic battery time-remaining estimate |
-| **REST API Mode** (`pyre serve`) | Expose all metrics as structured JSON REST endpoints (`GET /api/cpu`, `/api/all`, etc.) with optional API key auth |
-| **Process CPU Profiling** (`pyre profile-proc <pid>`) | Capture a 5-second `sample`/`spindump` for a misbehaving process and render an annotated call-tree summary |
-| **Watchdog Rules Engine** (`pyre watchdog`) | Persistent daemon that monitors metrics and executes configurable rules — e.g. "if CPU > 90% for 5 min → kill `photoanalysisd` → notify Slack" |
-| **Build System Tracker** (`pyre build`) | First-class tracking for `xcodebuild`, `cargo`, `make`, `bazel` — extends the existing Blender render tracker pattern |
-
-### Tier 3 — Big Bets
-
-| Feature | Description |
-|---|---|
-| **Network Topology Mapper** (`pyre topo`) | Visualize LAN peers, active connections, and routing hops as an ASCII diagram; auto-detects pyre-capable peers |
-| **Cloud Sync** (`pyre sync`) | Sync config profiles, alert thresholds, and anomaly history across multiple Macs via iCloud Drive or a custom S3/WebDAV backend |
+# 3. Development live mode
+npm run dev
 
-### Quality of Life
+# 4. Compile TypeScript bundle
+npm run build
 
-| Feature | Description |
-|---|---|
-| **Gaming / Performance Mode Profile** | `pyre live --profile gaming` — GPU + Thermal + Power panels only, 1 s interval, bar graph mode, minimal overlay |
-| **iOS Shortcut Integration** | Documented iOS Shortcut that runs `pyre check --plain` over SSH and displays a summary notification |
-| **Setup Wizard Polish** (`pyre setup`) | Guided first-run experience for `powermetrics` sudo, alert thresholds, theme selection, and webhook setup |
+# 5. Run test suite
+npm test
+```
 
 ---
 
 ## License
 
-MIT
+[MIT](LICENSE) © [somalip](https://github.com/somalip)