rigscope 0.1.0 → 0.1.2

package/README.md

@@ -1,158 +1,75 @@
 # Rigscope
 
-Your machines, in view. A self-hosted Linux system and process monitor for one machine or a small fleet. A collector samples each machine and connects outbound to one or more independently operated hubs. Each hub owns its users, permissions, SQLite history and alerts.
+Your machines, in view. A self-hosted Linux system and process monitor.
 
-Requires Linux, Node.js 26+ with npm, and a working systemd user manager for background services. Install a published release with:
+View CPU, memory, GPU, disk and network readings, browse History, inspect running
+processes and set alerts. Run a hub for the dashboard and a collector on each
+machine you want to monitor. The default installation runs both on this computer.
+
+## Install
+
+Requires **Linux, Node.js 26+ with npm, and systemd** for background services.
 
 ```sh
 npx --yes rigscope@latest install --boot
-~/.local/bin/rigscope
 ```
 
-If the npm release is not available yet, use the [release archive instructions](docs/installation.md#install-from-an-archive). No global npm installation or source checkout is required.
+Save the generated `owner` password and open the printed dashboard URL
+(normally `http://127.0.0.1:8081`). The services keep running after you close the
+terminal. `--boot` starts them at boot; omit it to start at login instead.
+
+Add `~/.local/bin` to PATH to use `rigscope`. You can also run
+`~/.local/bin/rigscope` directly. No global npm install or source checkout is needed.
 
-Save the generated `owner` password and open the printed URL. The default installation starts separate hub and collector services. `--boot` enables user lingering; without it, startup is at login. The installer reports any host authorization needed. Add `~/.local/bin` to PATH to use the commands below. Bare `rigscope` shows status.
+To try Rigscope in the terminal before installing services:
 
 ```sh
-rigscope status
-rigscope logs hub
-rigscope stop collector
-rigscope start collector
-rigscope upgrade
-rigscope rollback
+npx --yes rigscope@latest try
 ```
 
-For a foreground trial before installing services, run `npx --yes rigscope@latest try`. It uses separate trial state and stops with Ctrl+C. For a collector reporting to an existing hub, install with `--role collector`, then use `rigscope connect https://your-hub.example.com` and paste an Add machine grant at the private prompt. Each collector supports up to eight hubs.
+The trial uses separate data and stops with Ctrl+C.
 
-Rigscope includes real resource telemetry, fleet and machine views, durable History, on-demand Processes, alerts/webhooks and user/collector administration. Process inspection is read-only; kill, renice, service control, hub federation and clustering are outside this release. Missing readings remain unavailable, and stale data retains its freshness status.
+## Use it
 
-[Installation and hardware](docs/installation.md) · [Operations and recovery](docs/operations.md) · [Release notes](CHANGELOG.md) · [Development](docs/development.md) · [Releasing and verification](docs/releasing.md) · [Architecture](ARCHITECTURE.md) · [Design](DESIGN.md)
+| Task | Command or guide |
+| --- | --- |
+| Check services and the dashboard URL | `rigscope status` |
+| Follow hub logs | `rigscope logs hub --follow` |
+| Upgrade from npm | `rigscope upgrade` |
+| Stop or start the installation | `rigscope stop` / `rigscope start` |
+| Open the dashboard through Tailscale HTTPS | [Set up remote access](docs/installation.md#access-from-another-computer) |
+| Monitor another machine | [Add a collector](docs/installation.md#add-machines-and-hubs) |
+| Install a downloaded package | [Install from an archive](docs/installation.md#install-from-an-archive) |
 
-[Bottleneck readings](docs/bottlenecks.md) explains optional sensors and their limits. [Exports](docs/exports.md) describes visible-data CSV/JSON downloads. [Scale validation](docs/scale-validation.md) records synthetic workloads on one host; it is not a capacity guarantee.
+Each collector connects outbound to up to eight hubs. Each hub has its own users,
+permissions, history and alerts. Collectors need no incoming ports.
 
-Maintained by [Triet (@Triet1402)](https://github.com/Triet1402). Licensed under [MIT](LICENSE); dependency attribution is in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). See [SECURITY.md](SECURITY.md) to report vulnerabilities privately.
+## What to expect
 
-## Advanced configuration
+Rigscope is read-only: it does not kill processes, change priorities or control
+services on monitored machines. Missing sensor readings stay unavailable.
+NVIDIA and available AMD GPU counters are supported; Intel GPU readings are
+partial. See the [hardware notes](docs/installation.md#hardware).
 
-Managed installations use `rigscope config` and private settings described in
-[installation](docs/installation.md#hub-configuration). The environment variables
-below apply to source development and raw hub/collector services; setting them in
-your shell does not reconfigure a managed service.
+History is stored in SQLite. Process details are fetched while you view them and
+are never saved to History. See [Monitoring and alerts](docs/monitoring.md) for
+retention, sharing, freshness and notification behavior.
 
-Keep state/configuration directories 0700 and files 0600. Do not commit them.
+## Documentation
 
-| Hub variable | Behavior |
-| --- | --- |
-| `HUB_HOST`, `HUB_PORT` | Loopback-only listener; defaults `127.0.0.1:8081`. Port `0` is useful for isolated tests. |
-| `HUB_PUBLIC_ORIGIN`, `HUB_SOCKET_PATH` | Required together for remote mode. Exact HTTPS origin and private absolute Unix socket. No TCP listener in this mode. |
-| `HUB_DATABASE_PATH` | Authoritative SQLite telemetry/users/alerts/collector registry. Defaults beside `HUB_STATE_FILE`, otherwise `$XDG_STATE_HOME/rigscope/hub/telemetry.sqlite` (falling back to `~/.local/state`). |
-| `HUB_BROWSER_USERS` | First-run bootstrap JSON: `{username,passwordHash,machineIds,admin?}`. Scope is `"*"` or a machine-ID array; `[]` grants no machine access. |
-| `HUB_ADMIN_USERS` | Comma-separated usernames explicitly elevated during first import. When absent, an existing bootstrap account named `owner` is migrated as administrator. Other users need an explicit `admin:true`. |
-| `HUB_COLLECTORS` | First-run bootstrap JSON: `{collectorId,machineId,token}`; bounded by JSON bytes rather than machine count. Credentials travel only in bearer headers. |
-| `HUB_MAX_COLLECTOR_CONNECTIONS` | Concurrent collector socket budget; defaults to 100. Positive integer; tune to measured deployment capacity. |
-| `HUB_STATE_FILE` | Private enrollment-file import source for existing installations; enables the enrollment endpoint. Preserve it with deployment configuration for recovery. |
-| `HUB_ENROLLMENT_GRANTS` | Bootstrap grants `{token,expiresAt}`; at most 15 minutes. Consumed grants remain consumed across migration/restart. |
-
-From a source checkout, generate salted scrypt hashes with
-`scripts/hash-browser-password.cjs`, which reads passwords from stdin. Managed
-installation generates the initial account automatically. Keep hashes private. The database imports existing
-users/credentials once; later configuration restarts do not overwrite managed users
-or resurrect revoked credentials. Administration changes apply to active sessions
-and collector connections. Existing owner passwords and scopes are preserved.
-
-| Collector variable | Behavior |
+| Guide | Covers |
 | --- | --- |
-| `COLLECTOR_MODE` | `real` by default; `mock` is explicit synthetic telemetry and never scans real processes. |
-| `COLLECTOR_STATE_FILE` | Private persistent identity, enrolled destinations and pending enrollment recovery proof. Defaults under `$XDG_STATE_HOME/rigscope/collector.json`. |
-| `COLLECTOR_INTERVAL_MS` | Shared sampling cadence; defaults 1000 ms, minimum 100 ms. GPU polling has a 1-second local floor. |
-| `COLLECTOR_HUBS` | Optional explicit destinations `{url,token,sharing?,intervalMs?}`; at most eight. Otherwise use saved enrollment. |
-| `COLLECTOR_HOSTNAME` | Metadata only; real mode defaults to OS hostname. |
-
-Destination `sharing` accepts `cpu`, `memory`, `swap`, `gpus`, `disks`, `network`,
-`networkAddresses`, `processes`, `processArguments`. CPU/memory remain required when
-an object is supplied. Missing fields default to true, except swap follows memory
-and process arguments default false. Review local sharing before upgrading a
-restricted destination to broader metrics. Environment variables are never collected.
-Policy is applied before queueing, to restored pending metrics before sending, and
-to every process result separately for each hub.
-
-## Source enrollment, rotation and replacement
-
-For a managed installation, use `rigscope connect` as described in
-[Add machines and hubs](docs/installation.md#add-machines-and-hubs). The following
-commands require a source checkout with development dependencies installed.
-
-Create a short-lived grant through an authorized administration flow. On the machine,
-set `COLLECTOR_ENROLL_URL` to its full `ws[s]://…/api/collector/connect` URL and
-`COLLECTOR_ENROLL_TOKEN` privately, then run:
-
-```sh
-npm run collector:enroll
-```
-
-The collector saves a random recovery proof before requesting a credential. A retry
-after a lost successful response recovers the same credential using that proof;
-collector ID or hostname alone is insufficient. Restart the collector to apply changes.
-
-Rotation/replacement requires a grant explicitly bound to the existing hub-local
-machine mapping. Use `npm run collector:enroll -- --replace-enrollment` to replace a
-saved destination. Revocation invalidates open connections and old recovery proofs.
-Replacement never matches a machine by hostname or address.
-
-## Monitoring behavior and bounds
-
-- Samples are acknowledged only after a durable SQLite commit. Retries deduplicate
-  by collector/run/sequence. Replay fills History without replacing live state or
-  triggering historical threshold incidents.
-- Per-destination outboxes retain pending metrics across collector restart, prioritize
-  live telemetry, and bound replay/in-flight work. Defaults: ten minutes or 64 MiB
-  of queued JSON per destination, 256 MiB aggregate queued JSON. Separate physical
-  budgets count main database files plus WAL: 80 MiB per destination and 640 MiB
-  across eight destinations. SQLite page caps, bounded writes, checkpoints and
-  pressure rejection enforce these budgets; they are not OS filesystem quotas.
-- History defaults: raw 48 hours, one-minute rollups 30 days, one-hour rollups 400 days.
-  Rollups preserve minima/maxima. Queries have point, series, scanned-row and elapsed
-  budgets; partial results are disclosed. The hub defaults to a 2 GiB physical
-  database/WAL budget shared by telemetry, users, enrollment and alerts. Retention
-  protects the newest hour; when it cannot reclaim enough space, ingestion returns
-  busy without acknowledging records. Existing oversized databases enter pressure
-  mode; they are not destructively vacuumed at startup. Atomic writes may briefly
-  grow WAL before checkpointing; blocked checkpoints surface pressure and stop
-  subsequent ingestion rather than permitting continued growth.
-- Receipt freshness is `max(15 seconds, 3 × expected delivery interval)`. Unknown cadence
-  uses a disclosed 15-second fallback. Connection state, collection availability and
-  clock skew remain separate. Browser/hub clocks are not calibrated.
-- Process detail uses renewable viewer interests and one shared collector scan. Pausing,
-  hiding/closing a view, session termination or lease expiry releases extra work.
-  Process detail is never persisted. CPU is 100% per core; machine CPU is normalized
-  across logical cores. Missing/inaccessible readings remain unavailable.
-- User sessions are in memory with a fixed twelve-hour lifetime; a hub restart requires
-  signing in again. Users/scopes/password hashes and collector credentials persist.
-- Physical checks cover the Ubuntu RTX 3090 rig and the laptop’s RTX 5060 plus Radeon
-  860M iGPU. Intel sensor and ARM/RISC-V naming paths have deterministic fixture coverage;
-  physical validation for those paths remains outstanding. See the [hardware support notes](docs/installation.md#hardware).
-- There is no fixed machine-count limit. The default concurrent collector connection
-  budget is 100; [scale validation](docs/scale-validation.md) records synthetic
-  workloads up to 75 machines on one host and is not a capacity guarantee.
-  Remote kill/renice, service control, hub federation and clustering are out
-  of scope for this read-only release.
-
-## Alerts and administration
-
-Administration requires an explicit administrator role as well as machine scope.
-Use it to manage accounts/scopes, display names/tags, collector revocation and
-short-lived enrollment/replacement grants. User changes revoke existing browser
-sessions; credential changes close invalid collector connections. Wildcard scope
-alone does not grant administration.
-
-Alerts support above/below thresholds, duration, unavailable readings, missing
-receipts, maintenance and recovery. Value, unavailable and stale-receipt rules
-apply to every machine the hub tracks. Replay never opens historical incidents.
-Configure one HTTPS webhook channel in Alerts (loopback HTTP only for controlled
-test sinks). URL, headers and HMAC secret are write-only. Delivery is at-least-once:
-receivers should deduplicate the `Idempotency-Key`. Six attempts, a five-second
-request deadline and bounded persistent queues prevent unbounded delivery work.
-
-See [operations](docs/operations.md) for packaging, private service configuration,
-boot enablement, backups, tested restores, upgrades/rollback and measurements.
-The managed installer starts services by default; low-level archive tools print service commands for explicit execution.
+| [Installation](docs/installation.md) | npm, HTTPS, collectors, upgrades and hardware |
+| [Operations](docs/operations.md) | Diagnostics, backups, recovery and archive deployment |
+| [System installation](docs/system-installation.md) | Dedicated service accounts and system units |
+| [Configuration reference](docs/configuration.md) | Environment variables and source enrollment |
+| [Monitoring and alerts](docs/monitoring.md) | Data limits, sharing, users and webhooks |
+| [Sensor readings](docs/bottlenecks.md) / [Exports](docs/exports.md) | Reading meanings and downloads |
+| [Development](docs/development.md) / [Architecture](ARCHITECTURE.md) / [Design](DESIGN.md) | Source setup and implementation references |
+| [Releasing](docs/releasing.md) / [Release notes](CHANGELOG.md) | Publishing checks and version changes |
+| [Scale validation](docs/scale-validation.md) | Synthetic measurements on one host; no capacity guarantee |
+
+Published on [npm](https://www.npmjs.com/package/rigscope).
+Maintained by [Triet (@Triet1402)](https://github.com/Triet1402).
+Licensed under [MIT](LICENSE); see [dependency notices](THIRD_PARTY_NOTICES.md).
+Report vulnerabilities privately using [SECURITY.md](SECURITY.md).

package/dist/collector.cjs

@@ -5292,7 +5292,7 @@ function budget(value, fallback) {
 // package.json
 var package_default = {
   name: "rigscope",
-  version: "0.1.0",
+  version: "0.1.2",
   rigscopeConfigVersion: 2,
   private: false,
   engines: {
@@ -5360,6 +5360,9 @@ var package_default = {
     "README.md",
     "CHANGELOG.md",
     "docs/installation.md",
+    "docs/system-installation.md",
+    "docs/configuration.md",
+    "docs/monitoring.md",
     "docs/operations.md",
     "docs/bottlenecks.md",
     "docs/exports.md",
@@ -5368,6 +5371,11 @@ var package_default = {
     "docs/scale-validation.md",
     "docs/scale-validation.json",
     "docs/scale-acceptance.json",
+    "docs/stress-2026-11-04/README.md",
+    "docs/stress-2026-11-04/index.jsonl",
+    "docs/stress-2026-11-04/manifest.json",
+    "docs/stress-2026-11-04/results.html",
+    "docs/stress-2026-11-04/*ms.json",
     "ARCHITECTURE.md",
     "DESIGN.md",
     "LICENSE",

package/dist/hub.cjs

@@ -1741,7 +1741,7 @@ function describeError(error) {
 // package.json
 var package_default = {
   name: "rigscope",
-  version: "0.1.0",
+  version: "0.1.2",
   rigscopeConfigVersion: 2,
   private: false,
   engines: {
@@ -1809,6 +1809,9 @@ var package_default = {
     "README.md",
     "CHANGELOG.md",
     "docs/installation.md",
+    "docs/system-installation.md",
+    "docs/configuration.md",
+    "docs/monitoring.md",
     "docs/operations.md",
     "docs/bottlenecks.md",
     "docs/exports.md",
@@ -1817,6 +1820,11 @@ var package_default = {
     "docs/scale-validation.md",
     "docs/scale-validation.json",
     "docs/scale-acceptance.json",
+    "docs/stress-2026-11-04/README.md",
+    "docs/stress-2026-11-04/index.jsonl",
+    "docs/stress-2026-11-04/manifest.json",
+    "docs/stress-2026-11-04/results.html",
+    "docs/stress-2026-11-04/*ms.json",
     "ARCHITECTURE.md",
     "DESIGN.md",
     "LICENSE",
@@ -4054,7 +4062,8 @@ function queryHistory(db, q, budget = {}) {
     seriesRows = seriesRows.slice(0, Math.max(0, chosen.cutSeries));
     truncated = true;
   }
-  const stepMs = Math.max(chosen.resolutionMs, Math.ceil(rangeMs / maxPoints));
+  const stepMs = Math.max(1, Math.ceil(rangeMs / maxPoints / chosen.resolutionMs)) * chosen.resolutionMs;
+  const originMs = Math.floor(q.fromMs / stepMs) * stepMs;
   const series = [];
   for (const row of seriesRows) {
     if (performance.now() - started > maxElapsedMs) {
@@ -4070,7 +4079,7 @@ function queryHistory(db, q, budget = {}) {
       Number(row.series_id),
       fromBucketMs(chosen.tier, q.fromMs),
       q.toMs,
-      q.fromMs,
+      originMs,
       stepMs,
       // An additional per-series guard. Tier selection already keeps the total
       // under budget; this makes a single query bounded even if a custom
@@ -4236,8 +4245,8 @@ function readGaps(db, machineId, fromMs, toMs) {
     "SELECT from_ms, to_ms, dropped, reason FROM gaps WHERE machine_id = ? AND to_ms >= ? AND from_ms <= ? ORDER BY from_ms LIMIT ?"
   ).all(machineId, fromMs, toMs, MAX_GAPS);
   const missing = db.db.prepare(
-    "WITH ordered AS ( SELECT captured_at_ms, LAG(captured_at_ms) OVER (PARTITION BY machine_id ORDER BY captured_at_ms) AS prev_ms, expected_interval_ms FROM sample_receipts WHERE machine_id = ? AND captured_at_ms >= ? AND captured_at_ms <= ? ) SELECT prev_ms AS from_ms, captured_at_ms AS to_ms FROM ordered WHERE prev_ms IS NOT NULL AND captured_at_ms - prev_ms > MAX(15000, 3 * COALESCE(expected_interval_ms, 5000)) ORDER BY captured_at_ms LIMIT ?"
-  ).all(machineId, fromMs, toMs, MAX_GAPS);
+    "WITH before_window AS ( SELECT captured_at_ms, expected_interval_ms FROM sample_receipts WHERE machine_id = ? AND captured_at_ms < ? ORDER BY captured_at_ms DESC LIMIT 1 ), in_window AS ( SELECT captured_at_ms, expected_interval_ms FROM sample_receipts WHERE machine_id = ? AND captured_at_ms >= ? AND captured_at_ms <= ? ), ordered AS ( SELECT captured_at_ms, expected_interval_ms, LAG(captured_at_ms) OVER (ORDER BY captured_at_ms) AS prev_ms FROM (SELECT * FROM before_window UNION ALL SELECT * FROM in_window) ) SELECT MAX(prev_ms, ?) AS from_ms, captured_at_ms AS to_ms FROM ordered WHERE prev_ms IS NOT NULL AND captured_at_ms > ? AND captured_at_ms - prev_ms > MAX(15000, 3 * COALESCE(expected_interval_ms, 5000)) ORDER BY captured_at_ms LIMIT ?"
+  ).all(machineId, fromMs, machineId, fromMs, toMs, fromMs, fromMs, MAX_GAPS);
   const gaps = [
     ...dropped.map((row) => ({
       fromMs: Number(row.from_ms),

package/dist/ops.cjs

@@ -1559,6 +1559,9 @@ var PACKAGE_TOP_LEVEL = /* @__PURE__ */ new Set([
 ]);
 var PACKAGE_DOCS = /* @__PURE__ */ new Set([
   "docs/installation.md",
+  "docs/system-installation.md",
+  "docs/configuration.md",
+  "docs/monitoring.md",
   "docs/operations.md",
   "docs/development.md",
   "docs/releasing.md",
@@ -4080,7 +4083,8 @@ function queryHistory(db, q, budget = {}) {
     seriesRows = seriesRows.slice(0, Math.max(0, chosen.cutSeries));
     truncated = true;
   }
-  const stepMs = Math.max(chosen.resolutionMs, Math.ceil(rangeMs / maxPoints));
+  const stepMs = Math.max(1, Math.ceil(rangeMs / maxPoints / chosen.resolutionMs)) * chosen.resolutionMs;
+  const originMs = Math.floor(q.fromMs / stepMs) * stepMs;
   const series = [];
   for (const row of seriesRows) {
     if (performance.now() - started > maxElapsedMs) {
@@ -4096,7 +4100,7 @@ function queryHistory(db, q, budget = {}) {
       Number(row.series_id),
       fromBucketMs(chosen.tier, q.fromMs),
       q.toMs,
-      q.fromMs,
+      originMs,
       stepMs,
       // An additional per-series guard. Tier selection already keeps the total
       // under budget; this makes a single query bounded even if a custom
@@ -4262,8 +4266,8 @@ function readGaps(db, machineId, fromMs, toMs) {
     "SELECT from_ms, to_ms, dropped, reason FROM gaps WHERE machine_id = ? AND to_ms >= ? AND from_ms <= ? ORDER BY from_ms LIMIT ?"
   ).all(machineId, fromMs, toMs, MAX_GAPS);
   const missing = db.db.prepare(
-    "WITH ordered AS ( SELECT captured_at_ms, LAG(captured_at_ms) OVER (PARTITION BY machine_id ORDER BY captured_at_ms) AS prev_ms, expected_interval_ms FROM sample_receipts WHERE machine_id = ? AND captured_at_ms >= ? AND captured_at_ms <= ? ) SELECT prev_ms AS from_ms, captured_at_ms AS to_ms FROM ordered WHERE prev_ms IS NOT NULL AND captured_at_ms - prev_ms > MAX(15000, 3 * COALESCE(expected_interval_ms, 5000)) ORDER BY captured_at_ms LIMIT ?"
-  ).all(machineId, fromMs, toMs, MAX_GAPS);
+    "WITH before_window AS ( SELECT captured_at_ms, expected_interval_ms FROM sample_receipts WHERE machine_id = ? AND captured_at_ms < ? ORDER BY captured_at_ms DESC LIMIT 1 ), in_window AS ( SELECT captured_at_ms, expected_interval_ms FROM sample_receipts WHERE machine_id = ? AND captured_at_ms >= ? AND captured_at_ms <= ? ), ordered AS ( SELECT captured_at_ms, expected_interval_ms, LAG(captured_at_ms) OVER (ORDER BY captured_at_ms) AS prev_ms FROM (SELECT * FROM before_window UNION ALL SELECT * FROM in_window) ) SELECT MAX(prev_ms, ?) AS from_ms, captured_at_ms AS to_ms FROM ordered WHERE prev_ms IS NOT NULL AND captured_at_ms > ? AND captured_at_ms - prev_ms > MAX(15000, 3 * COALESCE(expected_interval_ms, 5000)) ORDER BY captured_at_ms LIMIT ?"
+  ).all(machineId, fromMs, machineId, fromMs, toMs, fromMs, fromMs, MAX_GAPS);
   const gaps = [
     ...dropped.map((row) => ({
       fromMs: Number(row.from_ms),

package/docs/bottlenecks.md

@@ -27,7 +27,7 @@ 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](installation.md#system-installation) grants its dedicated account persistent
+[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.
 

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

@@ -16,7 +16,7 @@ npm start
 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 README for configuration and destination sharing policy.
+`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