rigscope 0.0.0-stage → 0.1.1

package/docs/bottlenecks.md

@@ -0,0 +1,62 @@
+# Bottleneck telemetry
+
+Overview shows available bottleneck readings alongside existing resource panels.
+History records the same readings and offers separate charts for units such as
+temperature, watts and milliseconds. Select **CPU cores** in History to compare cores; the selection is saved per machine and applies to exports. Up to eight series use lines; larger selections use a scrollable heatmap. Drawing groups
+points toward a 150-point target per core while preserving extrema and gaps;
+downloads retain the loaded stored buckets rather than the drawing reduction.
+
+Readings are optional. An older collector, missing kernel interface, unreadable
+file or reset counter produces an unavailable reading rather than zero. GPU
+power and CPU package power are separate measurements; neither is whole-machine
+wall power.
+
+| Reading | Source and meaning |
+| --- | --- |
+| CPU temperature | Readable CPU hwmon sensors; package/Tctl/Tdie sensors take precedence over core sensors. Reports the hottest reading in the preferred class. |
+| CPU package power | Change in top-level RAPL package energy over monotonic elapsed time, summed across readable packages. Package subdomains are excluded. Requires two valid observations. |
+| CPU I/O wait | Change in procfs CPU iowait ticks, normalized by elapsed time and logical core count. |
+| CPU pressure | Linux PSI `some avg10`: percentage of time with tasks stalled for CPU over the recent ten-second window. |
+| Memory / I/O pressure | PSI `some avg10` and `full avg10`; `full` measures simultaneous stalls of all non-idle tasks. |
+| Disk read / write latency | Change in diskstats operation milliseconds divided by completed operations. No completed operations means unavailable latency. |
+| Disk utilization | Change in diskstats I/O-active milliseconds divided by elapsed time, capped at 100%. This is not a throughput-capacity estimate for parallel devices. |
+| Filesystem inode use | Used inode count divided by a positive total from `statfs`. Filesystems without usable inode totals remain unavailable. |
+| Memory / filesystem use | Used bytes divided by a positive total, on the 0–100 percent scale. |
+
+CPU temperature supports known CPU hwmon drivers, including `coretemp` and
+`k10temp`. CPU package power uses the Linux powercap `intel-rapl:N` interface,
+including compatible AMD implementations. Many systems restrict `energy_uj` to
+root. The collector remains unprivileged. The optional
+[system installer](system-installation.md#cpu-package-power) grants its dedicated account persistent
+read-only package-counter access; ordinary user installation leaves permissions
+under the operator's control.
+
+Counter resets invalidate the affected derived reading until a valid interval is
+available. RAPL wrap handling requires a readable energy range and a previous
+counter near its ceiling. Monitoring continues when an optional sensor fails.
+
+The new fields belong to the existing CPU, memory and disks sharing families.
+Withholding a family withholds its bottleneck fields for that destination too.
+
+Enhanced fields are negotiated independently for each hub. Upgraded collectors
+advertise wire revision `0.3.0`; upgraded hubs opt in with `bottleneck-v1` in their
+welcome. Older hubs receive the original metric shape, including replay. Older
+collectors receive the original welcome shape. Upgrade the hub and collector to
+see enhanced readings; an independent older destination continues receiving its
+existing metrics. Projection affects transmission, not the durable outbox record.
+
+Kernel references: [PSI](https://docs.kernel.org/accounting/psi.html),
+[powercap](https://docs.kernel.org/power/powercap/powercap.html), and
+[disk statistics](https://docs.kernel.org/admin-guide/iostats.html).
+
+## Warning presets
+
+In Alerts, choose a preset while creating a rule. The preset fills editable
+fields; **Create rule** is still required. Presets include high CPU, memory or
+disk nearly full, inode use, hot CPU/GPU, offline collectors, pressure stalls,
+I/O wait and disk latency/utilization. Resource presets use the selected machine's
+inventory, preferring its root filesystem when available.
+
+Percentage thresholds use 0–100. Preset thresholds and durations are starting
+points to review for the workload and hardware, not manufacturer safety limits.
+Unavailable readings/resources are identified before applying a preset.

package/docs/configuration.md

@@ -0,0 +1,85 @@
+# Configuration reference
+
+For an installation made with `rigscope install`, use `rigscope config` to find
+its private settings. See [Hub configuration](installation.md#hub-configuration)
+and [Remote access](installation.md#access-from-another-computer) for managed setup.
+
+The environment variables below apply to source development and services that
+run the hub or collector directly. Setting them in your shell does not change
+an installed background service. Keep private directories at mode `0700` and
+configuration files at `0600`; do not commit them.
+
+## Hub variables
+
+| Variable | Purpose and default |
+| --- | --- |
+| `HUB_HOST`, `HUB_PORT` | Local listener: `127.0.0.1:8081`. Only literal loopback addresses are accepted. Port `0` selects an unused port for tests. |
+| `HUB_PUBLIC_ORIGIN`, `HUB_SOCKET_PATH` | Remote access: set both the exact HTTPS origin and an absolute Unix socket path in a private directory. The hub then has no TCP listener. |
+| `HUB_DATABASE_PATH` | SQLite database for telemetry, users, alerts and the collector registry. Defaults beside `HUB_STATE_FILE`, or under `$XDG_STATE_HOME/rigscope/hub/` (falling back to `~/.local/state`). |
+| `HUB_BROWSER_USERS` | First-run users as JSON: `{username,passwordHash,machineIds,admin?}`. `machineIds` is `"*"` or a list; `[]` allows no machines. |
+| `HUB_ADMIN_USERS` | Comma-separated usernames to make administrators during first import. If omitted, an existing bootstrap account named `owner` becomes an administrator. Other users need an explicit `admin:true`. |
+| `HUB_COLLECTORS` | First-run collector credentials as JSON: `{collectorId,machineId,token}`. The limit applies to JSON bytes, not a fixed machine count. |
+| `HUB_MAX_COLLECTOR_CONNECTIONS` | Maximum concurrent collector connections. Positive integer; defaults to `100`. Choose a value based on measured capacity. |
+| `HUB_STATE_FILE` | Private enrollment file to import from an existing installation; also enables enrollment. Keep it with the deployment configuration for recovery. |
+| `HUB_ENROLLMENT_GRANTS` | Initial grants as JSON: `{token,expiresAt}`. Expiry must be within 15 minutes. Used grants stay consumed after import and restart. |
+
+### First-run users and credentials
+
+The database imports bootstrap users and collector credentials once. Later
+restarts do not overwrite managed users or restore revoked credentials. Use
+**Administration** to change users after the first start.
+
+The managed installer creates the initial account for you. From a source
+checkout, use `scripts/hash-browser-password.cjs` to generate salted scrypt
+hashes; it reads passwords from stdin. Keep hashes private.
+
+## Collector variables
+
+| Variable | Purpose and default |
+| --- | --- |
+| `COLLECTOR_MODE` | `real` by default. `mock` generates synthetic readings and never scans real processes. |
+| `COLLECTOR_STATE_FILE` | Private saved identity, destinations and enrollment recovery proof. Defaults to `$XDG_STATE_HOME/rigscope/collector.json` (falling back to `~/.local/state`). |
+| `COLLECTOR_INTERVAL_MS` | Sampling interval: `1000` ms by default, minimum `100` ms. GPU polling runs at most once per second. |
+| `COLLECTOR_HUBS` | Explicit destinations as JSON: `{url,token,sharing?,intervalMs?}`, up to eight. Otherwise the collector uses saved enrollment. |
+| `COLLECTOR_HOSTNAME` | Display metadata; defaults to the OS hostname in real mode. |
+
+### Sharing settings
+
+Each destination's `sharing` object accepts `cpu`, `memory`, `swap`, `gpus`,
+`disks`, `network`, `networkAddresses`, `processes` and `processArguments`.
+When supplying an object, CPU and memory must remain enabled.
+
+Omitted fields default to true, except `swap` follows `memory` and
+`processArguments` defaults to false. Managed enrollment starts with network
+addresses and full process arguments disabled. Review a destination's saved
+policy before expanding what it shares. Environment variables are never collected.
+
+The collector applies sharing rules before queueing samples, again before
+sending restored samples, and to each hub's process results. Restricting a policy
+also restricts pending records.
+
+## Source enrollment, rotation and replacement
+
+For a managed installation, follow [Add machines and hubs](installation.md#add-machines-and-hubs)
+using `rigscope connect`. The steps here require a source checkout with
+development dependencies installed.
+
+1. Create a short-lived grant through the hub's administration interface.
+2. Set `COLLECTOR_ENROLL_URL` to the full `ws[s]://…/api/collector/connect` URL.
+   Set `COLLECTOR_ENROLL_TOKEN` privately to the grant.
+3. Run:
+
+   ```sh
+   npm run collector:enroll
+   ```
+
+4. Remove the grant from the environment and restart the collector.
+
+The collector saves a random recovery proof before enrolling. If a successful
+response is lost, retrying with that proof recovers the same credential. A
+hostname or collector ID alone cannot recover it.
+
+Rotation or replacement needs a grant bound to the existing machine on that
+hub. Use `npm run collector:enroll -- --replace-enrollment` to replace a saved
+destination. Revocation closes existing connections and invalidates old recovery
+proofs. Replacement never identifies a machine by its hostname or address.

package/docs/development.md

@@ -0,0 +1,46 @@
+# Development
+
+Use Node.js 26+ and Linux for real collection. Keep private configuration outside Git, with directories 0700 and files 0600. Public fixture credentials are only for isolated tests.
+
+```sh
+npm ci
+npm run dev
+```
+
+Development uses `.next-dev`; production uses `.next`. Configure users and collector credentials privately before starting a hub. With no browser users it fails closed. Do not run two hubs against the same database or build output.
+
+```sh
+npm run build
+npm start
+# After enrollment, in a separate terminal or service:
+npm run collector:start
+```
+
+`npm run collector:enroll` uses `COLLECTOR_ENROLL_URL` and a private `COLLECTOR_ENROLL_TOKEN`. `npm run collector:mock` emits synthetic readings. Real collection continues without a browser. See the [configuration reference](configuration.md) for variables, enrollment and sharing settings.
+
+## HTTPS boundary
+
+Local HTTP is literal loopback only. Remote access requires `HUB_PUBLIC_ORIGIN` and `HUB_SOCKET_PATH` together: an exact HTTPS origin and an absolute Unix socket inside a private directory. The TLS reverse proxy must support WebSocket upgrades, unbuffered SSE, the configured Host and long-lived connections. The remote-mode hub has no TCP listener. The CLI does not configure DNS, certificates, Tailscale or a proxy.
+
+Cookies are Secure and HttpOnly remotely; same-origin validation and machine scope apply to queries, streams and mutations. A hub restart invalidates in-memory sessions. Development HMR upgrades must reach Next.js while collector upgrades reach `/api/collector/connect`. Browser sign-in during development reconnects to the authenticated socket.
+
+```sh
+curl --fail --silent --unix-socket /path/private/hub.sock \
+  -H 'Host: monitor.example.invalid' http://localhost/api/health
+npm run validate:https
+```
+
+The validation command checks an already configured endpoint. Supply its `RIGSCOPE_VALIDATE_*` settings privately; inspect `scripts/validate-https.cjs` for the exact inputs. It does not deploy or change credentials. Health checks and anonymous rejection alone do not prove an authenticated owner stream advances or reconnects.
+
+## Targeted verification
+
+| Command | Scope / default workers |
+| --- | --- |
+| `npm test` | Source tests; 4 concurrent files, `RIGSCOPE_TEST_CONCURRENCY` |
+| `npm run test:runtime` | Packaged runtime topology/auth/durability; 4 concurrent files, `RIGSCOPE_RUNTIME_TEST_CONCURRENCY` |
+| `npm run test:dev` | Development/HMR integration; 1 file at a time, `RIGSCOPE_DEV_TEST_CONCURRENCY` |
+| `npm run build:ui` | Production UI and TypeScript; `RIGSCOPE_BUILD_WORKERS`, default `min(4, available CPUs)` |
+| `npm run build:runtime` | Hub, collector, CLI and operations bundles |
+| `npm run typecheck` | Repository TypeScript check |
+
+Run the narrow checks relevant to the change. Build the UI once before runtime integration tests that require it; avoid duplicate unchanged builds. Tests use isolated state and never authorize touching host services or private installed data. `RIGSCOPE_REAL_HW=1 npx tsx --test tests/sampling-real.test.ts` explicitly opts into host collection. See [releasing](releasing.md) for package validation and evidence boundaries.

package/docs/exports.md

@@ -0,0 +1,39 @@
+# Export monitoring data
+
+History and Processes provide CSV and JSON download controls. Exports use the data
+already loaded in the browser; downloading does not request more history or trigger
+a process scan. Access remains scoped to the signed-in user's machines.
+
+## History
+
+Exports include the selected metrics and visible series. Hidden GPU cards and
+legend series are excluded. The document records the machine, time range, units,
+load time, resolution and partial-result status. Rolled-up buckets retain their
+minimum, maximum and average; these are not individual raw samples.
+
+Unavailable numeric values remain empty in CSV and null in JSON. Recorded gaps
+include their interval and available reason/drop count. Selected metrics without
+stored data are identified separately. The JSON summary's
+`averageOfBucketAverages` is an average of the loaded buckets, not a weighted
+average of all underlying raw samples.
+
+The CSV begins with metadata rows, followed by a `record_type` table containing
+`bucket` and `gap` records. JSON includes equivalent structured metadata and series.
+
+## Processes
+
+Exports follow the current search, sort and view. Application view includes each
+matching group's processes; tree view retains depth. Snapshot capture time,
+receipt time, freshness, unreadable-process count and collector truncation are
+included. A paused or stale snapshot is labeled accordingly.
+
+The exported fields are process name, PID, user, application/group, tree depth,
+CPU percentage, resident memory, GPU memory, read/write rates and thread count.
+Command arguments and environment data are not exported. CSV begins with snapshot
+metadata, followed by the process table; JSON preserves the same scope explicitly.
+
+## Files
+
+Downloads use a machine slug and UTC timestamp. Text cells that could be treated
+as spreadsheet formulas receive an apostrophe prefix in CSV. Numeric measurements
+remain numeric. JSON preserves original text without spreadsheet-specific changes.

package/docs/installation.md

@@ -0,0 +1,306 @@
+# Installation
+
+Start with [npm installation](#install-from-npm). For a shared dashboard, see
+[remote access](#access-from-another-computer) and [adding machines](#add-machines-and-hubs).
+[Upgrades](#upgrades) and [troubleshooting](#troubleshooting) cover existing installs.
+
+## Install from npm
+
+Requires Linux, Node.js 26+ with npm, and a working systemd user manager. Install
+Node.js first; Rigscope uses that Node executable for its background services.
+
+```sh
+npx --yes rigscope@latest install --boot
+```
+
+Save the generated `owner` password and open the printed URL, normally
+`http://127.0.0.1:8081`. The password is shown only when the account is first
+created. An existing installation keeps its account and password.
+
+The installer starts a hub and a collector in the background. Closing the
+terminal does not stop them. `--boot` enables startup at boot, including before
+login. If the host requires authorization, the installer prints the recovery
+command. Omit `--boot` to start at login instead.
+
+Add `~/.local/bin` to PATH, or run `~/.local/bin/rigscope` directly. No global npm
+install or source checkout is needed. The launcher and services use the installed
+runtime, so removing the npx cache does not break them.
+
+Releases are on [npm](https://www.npmjs.com/package/rigscope). `@latest` selects
+the current stable release; replace it with `@0.1.0` to select that exact version.
+
+### Installation options
+
+Append these options to `npx --yes rigscope@latest install`:
+
+| Goal | Options |
+| --- | --- |
+| Monitor this computer | `--boot` |
+| Send readings to another hub | `--role collector --boot` |
+| Host a dashboard over HTTPS and monitor this computer | `--origin https://hub.example.com --boot` |
+| Host a dashboard without collecting local readings | `--role hub --origin https://hub.example.com --boot` |
+| Use another local port | `--port 8086 --boot` |
+| Leave a new installation stopped | `--no-start` |
+| Disable startup at login | `--no-enable` |
+
+Repeating `install` repairs the services, launcher and startup settings. It keeps
+the existing runtime and credentials; use `rigscope upgrade` to update the code.
+`--no-start` does not stop a service that is already running.
+
+### Install from an archive
+
+For a downloaded package or one built from source, run from the directory
+containing the archive, or give its absolute path:
+
+```sh
+npx --yes --package ./rigscope-0.1.0.tgz rigscope install --boot
+```
+
+The same installation options apply. npm still needs registry access or cached
+production dependencies; the archive alone is not a complete offline installer.
+
+## Everyday commands and installation selection
+
+Run only the command for the task you want:
+
+| Task | Command |
+| --- | --- |
+| Check services, versions and the dashboard URL | `rigscope status` (or just `rigscope`) |
+| Start or stop | `rigscope start` / `rigscope stop` |
+| Restart the hub | `rigscope restart hub` |
+| Stop local collection | `rigscope stop collector` |
+| Follow logs | `rigscope logs --follow` |
+| Check configuration, services and sensor access | `rigscope doctor` |
+| Remove services and the managed runtime | `rigscope uninstall` |
+
+`start` is safe to repeat. `logs` shows the last 100 journal lines by default.
+`enable` and `disable` control the hub and collector independently; the initial
+role is a preset. Use `rigscope enable collector` to add local collection to a
+hub-only installation.
+
+`uninstall` keeps accounts, history, identity, pending samples and backups.
+Reinstalling reuses that data, including the existing password.
+
+## Access from another computer
+
+Run the commands on the hub machine. The examples use Tailscale already signed
+in, with HTTPS enabled. Replace `machine.example.ts.net` with the hub's Tailscale
+DNS name. Choose the section for a new or existing installation.
+
+### New HTTPS installation
+
+```sh
+npx --yes rigscope@latest install \
+  --origin https://machine.example.ts.net:8081 --boot
+tailscale serve --bg --tls-terminated-tcp=8081 \
+  "unix:$HOME/.local/state/rigscope/run/hub.sock"
+```
+
+### Convert a retained localhost installation
+
+If you already installed for localhost, change access without reinstalling:
+
+```sh
+rigscope stop
+rigscope configure --origin https://machine.example.ts.net:8081
+tailscale serve --bg --tls-terminated-tcp=8081 \
+  "unix:$HOME/.local/state/rigscope/run/hub.sock"
+rigscope start
+```
+
+This keeps accounts, history and collector credentials. It updates the local
+collector's destination and moves its pending samples. Both services must be
+stopped during conversion. See [Access changes](operations.md#access-changes)
+for backup and queue checks.
+
+### Open and check the dashboard
+
+Open `https://machine.example.ts.net:8081/` from a device allowed to reach the
+hub through Tailscale. Sign in with the existing account or the password printed
+at first installation. The viewing device needs no Rigscope installation.
+
+```sh
+rigscope status
+tailscale serve status
+```
+
+The forwarding command changes only port 8081 and keeps other Serve routes.
+Use the socket path printed by Rigscope if you chose another state directory.
+`--bg` keeps the route active after the terminal closes and across reboots.
+
+Use TLS-terminated TCP forwarding to preserve the request's Host header,
+including its port. See the [Tailscale Serve reference](https://tailscale.com/docs/reference/tailscale-cli/serve).
+Remote mode listens on a private Unix socket instead of a plaintext TCP port;
+collectors connect through HTTPS with certificate validation.
+
+### Return to localhost
+
+```sh
+rigscope stop
+rigscope configure --local
+tailscale serve --bg --tls-terminated-tcp=8081 off
+rigscope start
+```
+
+If you already uninstalled, change retained settings through the package entry
+point, then reinstall:
+
+```sh
+npx --yes rigscope@latest configure \
+  --origin https://machine.example.ts.net:8081
+npx --yes rigscope@latest install --boot
+```
+
+## Add machines and hubs
+
+1. On the hub, choose **Add machine**, then **New machine**. Create a connection
+   grant; it can be used once and expires within 15 minutes.
+2. On the machine to monitor, run:
+
+   ```sh
+   npx --yes rigscope@latest install --role collector --boot
+   ~/.local/bin/rigscope connect https://hub.example.com
+   ```
+
+3. Paste the grant at the private prompt. The collector starts after enrollment.
+   Use `connect --no-start` to enroll without starting it.
+
+Collectors connect outbound and need no incoming port or root access. Each can
+send to up to eight hubs. Sharing is separate for each hub; network addresses
+and full process arguments start disabled. See [Collection and sharing](monitoring.md#collection-and-sharing).
+
+Stop a running collector before changing its destinations. To replace an
+existing machine credential, create a grant bound to that machine and use
+`connect --replace`. For unattended enrollment, use `--token-file` with an owned
+private file and delete it afterward; do not put the grant on the command line.
+
+## Explicit foreground trial
+
+```sh
+npx --yes rigscope@latest try
+```
+
+Ctrl+C stops the trial. It uses separate data at `~/.local/state/rigscope-trial`
+and port 8082. Trial accounts and history persist. Use `try --state-dir PATH
+--port PORT` to choose another trial directory and port.
+
+To run an existing installation in the terminal, stop its background service
+first, then use `rigscope start --foreground`. This does not install services.
+A managed runtime directory cannot be used for `try`.
+
+## Hub configuration
+
+`rigscope config` prints the private `config.json` path. The installed launcher
+selects its own state directory. `--state-dir PATH` or `RIGSCOPE_STATE_DIR`
+selects another installation, with separate data and service names.
+
+Settings include component enablement, port, HTTPS origin and socket. Keep state
+directories at mode `0700` and configuration files at `0600`. Restart after edits.
+Use `configure` for access changes and **Administration** for users: editing
+first-run password hashes does not change an account already stored in SQLite.
+
+There is no fixed machine-count limit. The default connection limit is 100.
+Set `maxCollectorConnections` in private `config.json` and restart to change it.
+For direct hub/collector services, see the [environment reference](configuration.md).
+For another HTTPS proxy, see the [proxy requirements](development.md#https-boundary).
+
+## Upgrades
+
+Use the installed command:
+
+```sh
+rigscope upgrade
+```
+
+It gets `rigscope@latest` from npm, backs up the hub database and replaces the
+managed runtime. Accounts, history and collector settings are retained. Only
+components that were running are restarted; startup settings stay the same.
+
+| Alternative | Command |
+| --- | --- |
+| Select an exact published version | `rigscope upgrade --from rigscope@0.1.0` |
+| Install a local archive | `rigscope upgrade --from ./rigscope-VERSION.tgz` |
+| Return to the retained previous runtime | `rigscope rollback` |
+
+A fresh installation has no previous runtime to roll back to. Updating a global
+npm package does not update this runtime. Do not move runtime directories or run
+old code against a newer database. See [Upgrade and rollback checks](operations.md#managed-cli-operations)
+for health checks, failure recovery, database compatibility and backup selection.
+Keep separate backups outside the machine.
+
+## Troubleshooting
+
+### No password was printed
+
+The `owner` password appears only when the account is created. Reinstalling with
+saved settings keeps the old password. If you lost it, stop the installation
+and reset it at a private prompt:
+
+```sh
+rigscope stop
+rigscope recover-password --user owner
+rigscope start
+```
+
+Recovery keeps history and collector credentials. Sign in again afterward.
+It changes an existing account; it does not create a missing user or grant
+administrator access. See [Password recovery](operations.md#password-recovery).
+
+### An old command opens, or uninstall is unknown
+
+If installation prints `Keeping existing command at …`, another launcher already
+occupies that path. The installer leaves it intact and prints a usable `Command:`
+path for the new CLI. Use that path, or invoke the published CLI directly:
+
+```sh
+npx --yes rigscope@latest status
+npx --yes rigscope@latest uninstall
+```
+
+Choose the operation you need; `uninstall` removes this installation and retains
+its data. Use `ls -l ~/.local/bin/rigscope` to check for a link to an older
+checkout. Back up a confirmed old launcher before removing it, then repeat
+`install` to create the new launcher. Older services with other names may need
+separate cleanup; do not stop unrelated services.
+
+### The hub keeps restarting
+
+Check `rigscope logs hub` and `rigscope doctor`. If port 8081 is already in use,
+identify the listener before stopping anything. For a fresh install, choose an
+unused port with `install --port 8086 --boot`, or use HTTPS mode with a private
+socket. An existing installation refuses a different `--port` during reinstall;
+reinstalling alone does not reset its settings.
+
+## Hardware
+
+Collection supports Linux. CPU, memory and process readings come from procfs.
+ARM and RISC-V CPU names are recognized; utilization uses per-core counters.
+
+| Hardware | Available readings | Limit |
+| --- | --- | --- |
+| NVIDIA | Utilization, dedicated memory, temperature, power; compute-process memory | Requires `nvidia-smi` |
+| AMD discrete GPU | Busy percentage, dedicated VRAM, temperature, power | Requires readable amdgpu sysfs/hwmon counters |
+| AMD integrated GPU | Busy percentage and available hardware sensors | Reports only driver-provided VRAM; does not estimate shared memory |
+| Intel discrete or integrated GPU | Available hwmon temperature/power and optional driver counters | Partial support; most utilization readings remain unavailable |
+| ASPEED/other display adapters | Inventory | No telemetry backend |
+
+On AMD APUs the reported power counter can include CPU/SoC power; it is not a
+GPU-exclusive power measurement.
+
+Drivers, permissions and kernel versions determine which readings are available.
+Missing readings never become zeros. Intel temperature or power support does not
+imply utilization or per-process GPU memory support. Inventory refresh detects
+hotplug changes. AMD/Intel adapters use PCI-based IDs; NVIDIA uses GPU UUIDs.
+
+AMD uses the kernel's [amdgpu sysfs and hwmon interfaces](https://docs.kernel.org/gpu/amdgpu/thermal.html).
+Physical checks cover an Ubuntu RTX 3090 rig and a laptop with an RTX 5060 and
+Radeon 860M, including iGPU utilization, memory, temperature and power stored by
+the hub. Intel sensors and ARM/RISC-V naming have fixture tests but still need
+physical validation. macOS, Windows and Apple GPU collection are not supported.
+
+
+## System installation
+
+For dedicated service accounts, system units and CPU package-power permissions,
+see [System installation](system-installation.md). The default npm installation
+above runs as your own user.

package/docs/monitoring.md

@@ -0,0 +1,112 @@
+# Monitoring and alerts
+
+This guide explains what Rigscope collects, how long it keeps data, and how
+access and alerts work. For setup, see [Installation](installation.md).
+
+## Collection and sharing
+
+Each collector samples its machine once and sends readings independently to up
+to eight hubs. Collection continues when no browser is open. Each hub owns its
+users, permissions, history and alerts.
+
+Managed enrollment shares CPU, memory, swap, GPU, disk and network readings,
+plus on-demand process details. Network addresses and full process arguments
+start disabled. Sharing is set separately for each hub; see the
+[configuration reference](configuration.md#sharing-settings).
+
+Missing or inaccessible readings stay unavailable. GPU support depends on the
+driver and readable counters; see [Hardware](installation.md#hardware) and
+[Sensor readings](bottlenecks.md).
+
+## History and delivery
+
+The hub acknowledges samples after committing them to SQLite. A collector keeps
+unacknowledged samples in a persistent queue for each hub and retries after a
+disconnect. The hub removes duplicates using the collector, run and sequence IDs.
+Replayed samples fill History without replacing current live readings or opening
+alerts for past threshold crossings.
+
+Default retention:
+
+| Resolution | Kept for |
+| --- | --- |
+| Raw samples | 48 hours |
+| One-minute summaries | 30 days |
+| One-hour summaries | 400 days |
+
+Summaries retain minimum and maximum values. History queries limit the number
+of points, series, scanned rows and time spent. The UI marks partial results.
+
+Hover over a History or Overview recent-usage chart to inspect a recorded time
+and its bucket averages. The time marker follows across charts in the same view;
+per-core heatmaps show the bucket peak at that time. Missing readings stay
+unavailable. With a chart focused, use Left/Right arrows to move between readings,
+Home/End to jump to the first/last reading, and Escape to dismiss the marker.
+
+### Storage limits
+
+Each collector queue keeps up to ten minutes or 64 MiB of queued JSON per hub,
+with a 256 MiB total JSON limit. Physical SQLite files, including WAL files,
+have separate limits of 80 MiB per hub and 640 MiB across eight hubs.
+
+The hub's default database limit is 2 GiB, including its WAL file and all tables.
+Retention protects the newest hour of telemetry. If old-data cleanup cannot
+free enough space, the hub stops acknowledging new samples and collectors retry.
+Existing oversized databases report pressure; startup does not run a destructive
+cleanup.
+
+These are application limits, not filesystem quotas. A transaction can briefly
+grow the WAL before checkpointing. Blocked checkpoints stop further ingestion
+instead of allowing continued growth. Keep disk space for backups and sidecar
+files. See [Storage pressure recovery](operations.md#storage-budgets-and-pressure-recovery).
+
+## Live readings and process details
+
+A receipt becomes stale after `max(15 seconds, 3 × expected delivery interval)`.
+If the cadence is unknown, Rigscope uses 15 seconds and discloses that fallback.
+Connection status, unavailable readings and clock skew are reported separately.
+Rigscope does not synchronize the browser and hub clocks.
+
+Process details are scanned while viewers request them. Viewers share one
+collector scan. Pausing, hiding or closing the view releases the extra work;
+expired viewer requests and ended sessions do the same. Process details are
+never persisted.
+
+Process CPU uses 100% per logical core. Machine CPU is normalized across all
+logical cores. See [Exports](exports.md) for CSV and JSON behavior.
+
+## Users and administration
+
+Use **Administration** to manage users, machine access, names, tags, collector
+revocation and enrollment grants. Administration requires an administrator role
+and the appropriate machine access. Access to all machines alone does not make
+a user an administrator.
+
+User changes revoke existing browser sessions. Collector credential changes
+close connections that no longer have access. User records and collector
+credentials persist in SQLite. Browser sessions stay in memory, expire after
+12 hours and end when the hub restarts.
+
+## Alerts and webhooks
+
+Alerts support above/below thresholds, durations, unavailable readings, missing
+receipts, maintenance and recovery. Value, unavailable and stale-receipt rules
+apply to the machines tracked by that hub. Replayed samples do not open past
+incidents.
+
+In **Alerts**, configure one HTTPS webhook channel. Its URL, headers and HMAC
+secret are write-only. Loopback HTTP is allowed for controlled test sinks.
+Delivery may be repeated: receivers should deduplicate the `Idempotency-Key`.
+Rigscope makes up to six attempts, with a five-second deadline per request and
+bounded persistent queues.
+
+## Scale and limits
+
+There is no fixed machine-count limit. The default limit is 100 concurrent
+collector connections. [Scale validation](scale-validation.md) records synthetic
+workloads of up to 75 machines on one host; those results are not a capacity
+guarantee.
+
+Rigscope does not kill processes, change their priorities, control remote
+services, federate hubs or provide a clustered hub. See the
+[hardware notes](installation.md#hardware) for physical testing and sensor limits.