rigscope 0.1.8 → 0.2.1

package/docs/configuration.md

@@ -17,7 +17,21 @@ configuration files at `0600`; do not commit them.
 | --- | --- |
 | `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_DATABASE_PATH` | SQLite database for control state (users, alerts and the collector registry) and, only when enabled, telemetry history. Defaults beside `HUB_STATE_FILE`, or under `$XDG_STATE_HOME/rigscope/hub/` (falling back to `~/.local/state`). |
+| `HUB_TELEMETRY_MODE` | `memory` (default) keeps bounded history in RAM and writes no routine telemetry rows. `persistent` opts into compact SQLite summaries. See [telemetry storage](telemetry-storage.md). |
+| `HUB_HISTORY_MEMORY_BYTES` | Global RAM budget for memory history. Default `134217728` (128 MiB). |
+| `HUB_TELEMETRY_FLUSH_MS` | Persistent-mode write interval. Default and maximum `5000` ms (5 seconds); allowed 1000–5000. The bound keeps one commit inside the 64-batch collector window at the fastest supported 100 ms cadence and well below the collector's 30 s ack timeout. |
+| `HUB_RETENTION_RAW_MS` | Persistent raw-mode retention. Default 2 days. Persistent summary mode does not write raw rows. |
+| `HUB_RETENTION_10S_MS` | Ten-second summary retention in persistent mode. Default 2 hours. |
+| `HUB_RETENTION_1M_MS` | One-minute rollup retention. Default 30 days. |
+| `HUB_RETENTION_1H_MS` | One-hour rollup retention. Default 400 days. |
+| `HUB_RECEIPT_RETENTION_MS` | Deduplication receipt lifetime, independent of chart retention. Default 7 days. |
+| `HUB_GAP_RETENTION_MS` | Explicit collector gap retention. Default 400 days. |
+| `HUB_RECORDINGS_DIR` | Private directory for explicit recordings. Default `recordings/` beside the hub database (0700 directory, 0600 files). |
+| `HUB_RECORDING_MAX_DURATION_MS` | Maximum recording duration. Default 1 hour; maximum 24 hours. |
+| `HUB_RECORDING_MAX_BYTES` | Maximum recording file size. Default 64 MiB; maximum 1 GiB. |
+| `HUB_RECORDING_BACKLOG_MS` | Recent RAM history a new recording may include. Default 10 minutes. |
+| `HUB_RECORDING_MAX_ACTIVE` | Concurrent active recordings. Default 4; maximum 32. |
 | `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. |
@@ -25,6 +39,24 @@ configuration files at `0600`; do not commit them.
 | `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. |
 
+### Telemetry history mode
+
+The default `HUB_TELEMETRY_MODE=memory` keeps recent charts in a bounded RAM
+budget and deliberately loses telemetry history when the hub restarts. Users,
+credentials, enrollment, settings and alert records remain in SQLite.
+
+Set `HUB_TELEMETRY_MODE=persistent` to keep compact ten-second summaries, with
+one transaction roughly every `HUB_TELEMETRY_FLUSH_MS` (five seconds by
+default). Collectors still acknowledge only after that transaction commits, so
+the flush interval cannot exceed the collector's 64-batch in-flight window at
+its advertised cadence; the hub rejects values above five seconds. See
+[telemetry storage](telemetry-storage.md) for aggregation, deduplication,
+recording and reset details.
+
+Switching an existing installation to memory mode does not automatically delete
+old telemetry rows. They are ignored, but can be reclaimed explicitly with
+`ops reset-telemetry` after stopping the hub (see [operations](operations.md)).
+
 ### First-run users and credentials
 
 The database imports bootstrap users and collector credentials once. Later
@@ -44,6 +76,7 @@ hashes; it reads passwords from stdin. Keep hashes private.
 | `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. |
+| `COLLECTOR_QUEUE_MODE` | Where unacknowledged samples wait: `memory` by default (RAM, no queue written to disk, lost on collector restart) or `durable` (a SQLite outbox per destination that survives a collector restart, at one database write per sample). Bounds are identical: 10 minutes and 64 MiB per destination. |
 
 ### Sharing settings
 

package/docs/installation.md

@@ -27,7 +27,7 @@ install or source checkout is needed. The launcher and services use the installe
 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.8` to select that exact version.
+the current stable release; replace it with `@0.2.0` to select that exact version.
 
 ### Installation options
 
@@ -53,7 +53,7 @@ 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.8.tgz rigscope install --boot
+npx --yes --package ./rigscope-0.2.0.tgz rigscope install --boot
 ```
 
 The same installation options apply. npm still needs registry access or cached
@@ -156,7 +156,9 @@ tailscale serve --bg --tls-terminated-tcp=8081 \
 ```
 
 This keeps accounts, history and collector credentials. It updates the local
-collector's destination and moves its pending samples. Rigscope asks to stop
+collector's destination and moves its pending samples, which is only relevant in
+`COLLECTOR_QUEUE_MODE=durable`: the default RAM queue drains with the collector.
+Rigscope asks to stop
 running components during conversion and resumes them afterward. See [Access changes](operations.md#access-changes)
 for backup and queue checks.
 
@@ -290,12 +292,16 @@ npx --yes rigscope@latest install --boot
 ```
 
 Both paths stop the owned services and reset the pre-canonical configuration and
-history. Future upgrades that stay in the canonical format keep accounts, history,
-settings and collector identities.
+history. Upgrades that stay in the canonical format keep accounts, settings and
+collector identities; the first one after the RAM-first release additionally
+completes a one-time transition that discards machine-derived history and
+pre-RAM-first durable collector queues once. Later upgrades preserve durable
+history and queues. See
+[telemetry storage](telemetry-storage.md#the-one-time-machine-data-transition).
 
 | Alternative | Command |
 | --- | --- |
-| Select an exact published version | `rigscope upgrade --from rigscope@0.1.8` |
+| Select an exact published version | `rigscope upgrade --from rigscope@0.2.0` |
 | Install a local archive | `rigscope upgrade --from ./rigscope-VERSION.tgz` |
 | Return to the retained previous runtime | `rigscope rollback` |
 

package/docs/monitoring.md

@@ -20,22 +20,61 @@ driver and readable counters; see [Hardware](installation.md#hardware) and
 
 ## 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.
+History is **RAM-only by default**. Live readings update immediately, recent
+charts come from a bounded memory budget, and telemetry history disappears when
+the hub restarts. Users, credentials, enrollment, settings, alert records,
+machine names/tags and inventory remain persistent.
+
+In memory mode the collector's acknowledgement means the hub accepted the sample
+into RAM. The collector queues pending samples in RAM and retries after a
+disconnect, so it gains no disk work from the hub's choice and writes no queue
+of its own. Deduplication
+uses a compact per-run interval set for the hub process lifetime. Because both
+history and receipts disappear together on restart, a replay cannot double-count
+restored chart data.
+
+Set `HUB_TELEMETRY_MODE=persistent` to opt into disk history. The hub buffers a
+five-second window, publishes live state immediately, writes one compact
+transaction, and only then acknowledges. Replay deduplication uses durable
+receipts whose lifetime is independent of chart retention (default seven days).
 Replayed samples fill History without replacing current live readings or opening
-alerts for past threshold crossings.
+alerts for past threshold crossings. A graceful shutdown flushes pending
+summaries; after a crash the collector replays anything the hub never
+acknowledged, provided the collector itself kept it: only
+`COLLECTOR_QUEUE_MODE=durable` survives a collector restart.
 
-Default retention:
+Default memory history:
 
 | 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.
+| 1-second detail | 2 minutes |
+| 10-second summaries | 1 hour |
+| One-minute summaries | 24 hours |
+| One-hour summaries | 7 days |
+
+Per-core CPU keeps less detail; machine-wide and capacity metrics keep more.
+Persistent mode writes compact ten-second summaries and folds them into
+one-minute and one-hour tiers; it does not write a raw row per reading. It keeps
+10-second summaries for 2 hours, one-minute summaries for 30 days and hourly
+summaries for 400 days by default. Both modes retain minimum and maximum values,
+so short spikes remain visible, and both preserve explicit unavailable readings
+and gaps.
+
+RAM history is bounded by `HUB_HISTORY_MEMORY_BYTES` (default 128 MiB) across all
+machines. When the budget fills, the oldest fine-grained tiers are dropped first
+and new cardinality beyond the sustainable budget is rejected with visible
+pressure. History queries limit points, series, scanned rows and elapsed time;
+the UI marks partial results.
+
+### Recording
+
+Use **History → Recording** to start an explicit capture for the current
+machine and selected metrics. Choose a resolution from 1 second to 1 hour,
+a duration and whether to include recent RAM history. The capture is bounded by
+duration and bytes, survives restart through its private persisted output, and
+can be downloaded by its creator. Recording also works when chart history is
+temporary, which is the intended way to keep an incident snapshot. See
+[telemetry storage](telemetry-storage.md#recording).
 
 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;
@@ -49,11 +88,12 @@ 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.
+In persistent mode the hub's default database limit is 2 GiB, including WAL and
+all control tables. Retention protects the newest hour; 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. In memory mode old historical rows may still occupy the
+file until you run `ops reset-telemetry`; they are not read or updated.
 
 These are application limits, not filesystem quotas. A transaction can briefly
 grow the WAL before checkpointing. Blocked checkpoints stop further ingestion
@@ -92,7 +132,10 @@ credentials persist in SQLite. Browser sessions stay in memory, expire after
 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.
+incidents. Alert rules, incidents and pending notifications stay durable in both
+history modes; with no rules configured, live ingestion does not write per-sample
+alert progress. Enabling rules may write alert state on evaluation, which is
+operational state rather than telemetry history.
 
 In **Alerts**, configure one HTTPS webhook channel. Its URL, headers and HMAC
 secret are write-only. Loopback HTTP is allowed for controlled test sinks.

package/docs/operations.md

@@ -10,6 +10,7 @@ building and deploying from source.
 | Reset a lost password | [Password recovery](#password-recovery) |
 | Change localhost/HTTPS access | [Access changes](#access-changes) |
 | Back up or restore a database | [Database commands](#database-commands) |
+| Discard old telemetry history only | [Database commands](#database-commands) |
 | Plan what to back up | [Consistent backup set](#consistent-backup-set) |
 | Handle a full database or queue | [Storage pressure recovery](#storage-budgets-and-pressure-recovery) |
 
@@ -54,9 +55,26 @@ running, then checks:
 The health timeout is 25 seconds; change it with `--timeout SECONDS`. A failed
 start, migration or health check restores the previous runtime. It also restores
 the paired database backup if the old runtime cannot read the new schema,
-preserving the replaced database first.
-
-Credentials, collector identities and pending samples are retained.
+preserving the replaced database first — and additionally whenever the
+one-time machine-data transition described below had already discarded rows,
+even if the schema is compatible, because the loss there is the rows, not the
+schema.
+
+The first upgrade after the RAM-first release completes a one-time
+machine-data transition: it discards the previous design's on-disk machine
+history — telemetry rows and summaries, receipts, gaps, latest snapshots,
+inventory and machine-derived alert history — plus pre-RAM-first durable
+collector queues, once, even data previously opted into keeping. Machine
+display names/tags (`machine_meta`), accounts, sessions, enrollment and grants,
+settings, alert rules/jobs/webhook configuration and recordings are never
+discarded. A version-independent `machine-data-transition.json` marker in the
+state directory records completion; every later upgrade preserves durable
+history and queues you opt back into (`COLLECTOR_QUEUE_MODE=durable`, durable
+hub history). The upgrade output reports exactly what was discarded; a cleanup
+that cannot finish is shown as a warning and retried by the next upgrade
+instead of failing an otherwise healthy one. See
+[telemetry storage](telemetry-storage.md#the-one-time-machine-data-transition).
+Credentials and collector identities are always retained.
 `release-state.json` records which backup belongs to each runtime. Upgrading a
 stopped installation leaves it stopped and reports live checks as skipped.
 
@@ -66,7 +84,8 @@ release, stops the hub and collector completely, then removes
 the old configuration and history and installing the latest release fresh. Back
 up the state directory first if that history must be kept. There is no migration
 to the canonical format and no rollback to that old shape. Future upgrades that
-stay canonical keep accounts, history, settings and collector identities.
+stay canonical keep accounts, settings and collector identities, and — apart
+from the one-time transition above — durable history and queues.
 
 ### Roll back
 
@@ -191,7 +210,7 @@ The installer creates:
   hub.env                       private EnvironmentFile (0600, no secrets printed)
   collector.env                 private EnvironmentFile (0600)
   collector/collector.json      collector identity/enrollment (created by collector)
-  outbox/<sha256(url)[0:16]>/   per-destination collector outboxes
+  outbox/<sha256(url)[0:16]>/   per-destination queues, durable mode only
   backups/                      private pre-upgrade/pre-activation database copies
   install-state.json            canonical versions/schema backups, no credentials
   run/                          private runtime directory for a Unix socket
@@ -314,6 +333,9 @@ COLLECTOR_ENROLL_URL=ws://127.0.0.1:8081/api/collector/connect
 COLLECTOR_ENROLL_TOKEN=<one-use grant>
 COLLECTOR_MODE=real
 COLLECTOR_STATE_FILE=/home/operator/.local/state/rigscope/collector/collector.json
+# Optional: keep unacknowledged samples in a per-hub SQLite outbox so they
+# survive a collector restart. Default is RAM (no queue written to disk).
+# COLLECTOR_QUEUE_MODE=durable
 ```
 
 Remove the one-use grant after enrollment and start or restart the collector. The
@@ -369,6 +391,11 @@ node dist/ops.cjs restore \
   --database /path/telemetry.sqlite \
   --replace --confirm-stopped
 
+# Discard only telemetry history, preserving users/enrollment/settings/alerts.
+node dist/ops.cjs reset-telemetry \
+  --database /path/telemetry.sqlite \
+  --backup-dir /path/private-backups --confirm-stopped
+
 # Offline managed-user recovery; password comes from a private 0600 file.
 node dist/ops.cjs recover-admin \
   --database /path/telemetry.sqlite \
@@ -408,18 +435,24 @@ release must never be pointed at a newer schema. `inspect` reports this state.
 
 The database backup is not the whole installation. A restorable set is:
 
-1. Hub SQLite database: `telemetry.sqlite` (includes registry/admin/alerts).
-   Use `ops backup`; do not copy the main file alone while the hub is running.
+1. Hub SQLite database: `telemetry.sqlite` (includes registry/admin/alerts and
+   any opt-in persistent history). Use `ops backup`; do not copy the main file
+   alone while the hub is running.
 2. Enrollment/config state when configured: `HUB_STATE_FILE` (for
    example `hub/enrollment.json`, the import source for previously enrolled
    collectors) and the private hub environment file. These
    contain credentials: protect and copy them only between private locations.
 3. Collector identity/enrollment: `collector/collector.json`.
-4. Collector outboxes: `outbox/<destination-hash>/outbox.sqlite` per hub URL,
-   which may contain unacknowledged telemetry. Replay is at-least-once; the hub
-   deduplicates by collector/run/sequence.
+4. Collector queues, `outbox/<destination-hash>/outbox.sqlite` per hub URL, exist
+   only under `COLLECTOR_QUEUE_MODE=durable` and may contain unacknowledged
+   telemetry. Replay is at-least-once; the hub deduplicates by
+   collector/run/sequence. The default RAM queue holds nothing on disk, so there
+   is nothing to back up and nothing to restore.
 5. Optional operational metadata: `install-state.json`, units and the built
    release. Keep the release matching the database schema for rollback.
+6. Explicit recordings: the private `HUB_RECORDINGS_DIR` (default
+   `<hub database directory>/recordings`) if you want downloadable captures to
+   survive a restore. They are user output, not part of the database backup.
 
 For a consistent set, prefer stopping both services cleanly, then run the online
 database backup and copy the other private files. For an online backup, the SQLite
@@ -472,7 +505,10 @@ use the component controls in [System installation](system-installation.md#syste
 The collector uses only `/api/collector/connect` and the canonical record shape.
 There is no old-endpoint normalization, outbox migration or old-peer payload
 conversion. Reset unfinished installations and re-enroll their collectors;
-canonical upgrades retain their identities, credentials and pending samples.
+canonical upgrades retain their identities and credentials. Pending samples are
+retained by every upgrade after the one-time machine-data transition, which
+discards pre-RAM-first durable queues once; from then on
+`COLLECTOR_QUEUE_MODE=durable` content survives upgrades.
 
 ## Measurement
 
@@ -486,7 +522,18 @@ node dist/ops.cjs measure --machines 2 --batches 30 --records-per-batch 5 \
 It writes synthetic records through the real `TelemetryStore` into a
 temporary private database and reports accepted/rejected/busy counts, ingestion
 latency, event-loop delay/utilization, RSS, database/WAL size, store queue and
-flush counters, and one history-query latency. The output is labelled synthetic.
+flush counters, and one history-query latency.
+
+For the history-mode tradeoff, use the repeatable RAM-vs-persistent benchmark.
+It measures process-attributed disk writes, latency, RSS and rows:
+
+```sh
+npm run benchmark:telemetry -- --machines 2 --seconds 120
+npm run benchmark:telemetry -- --machines 10 --seconds 60 --json
+```
+
+Use `--dir` on a real filesystem; tmpfs does not account storage writes in
+`/proc/self/io`. See [telemetry storage](telemetry-storage.md#benchmark). The output is labelled synthetic.
 Defaults are intentionally small; upper bounds are 1,000 machines, 2,000 batches,
 32 records per batch and 100,000 records total. It never opens a service socket
 or contacts a hub. `--keep` retains the temporary directory for inspection. The
@@ -528,20 +575,29 @@ absolute regular file; use the release's `node_modules` installed with
 ## Storage budgets and pressure recovery
 
 Each Collector Hub connection owns policy filtering, cadence, inventory and its
-durable outbox submission. On restart, recovered metrics are sanitized with the
-current sharing policy before the connection starts; capture-time cadence is not
-reapplied to retained records. Endpoint upgrade recovery and aggregate budgets
-continue to use the existing outboxes. Hub startup restores stored telemetry,
+delivery queue submission. Under `COLLECTOR_QUEUE_MODE=durable`, recovered metrics
+are sanitized with the current sharing policy before the connection starts;
+capture-time cadence is not reapplied to retained records. Endpoint upgrade
+recovery and aggregate budgets continue to use the existing queues. The default
+RAM queue starts empty, so its bounds are enforced against RAM rather than disk. Hub startup restores stored telemetry,
 cadence, inventory and metadata through Sample ingestion while retaining a
 disconnected state until an authenticated Collector reconnects.
 
 The default hub main-file plus WAL budget is 2 GiB, shared by every SQLite table.
-The main file has a page-count limit; WAL reserves up to 128 MiB inside that budget.
-Telemetry writes return busy on pressure or SQLITE_FULL, with no receipt/ack for a
-failed transaction. Retention reclaims old raw/one-minute points in bounded chunks
-while preserving the newest hour; hourly rollups retain their configured age window.
-A full newest-hour working set must fit the deployment's budget. Outboxes retry
-while the operator frees space or provisions a larger supported configuration.
+The main file has a page-count limit; WAL reserves up to 128 MiB inside that budget
+and automatic checkpointing waits for a meaningful 32–64 MiB reserve where the
+budget permits. Persistent-mode writes return busy on pressure or SQLITE_FULL,
+with no receipt/ack for a failed transaction. Retention reclaims old raw or
+ten-second points and one-minute rollups in bounded chunks while preserving the
+newest hour; hourly rollups retain their configured age window. A full
+newest-hour working set must fit the deployment's budget. Outboxes retry while
+the operator frees space or provisions a larger supported configuration.
+
+Memory mode keeps only a bounded RAM budget (`HUB_HISTORY_MEMORY_BYTES`, default
+128 MiB). It does not write routine telemetry rows, but existing historical rows
+from an older installation still occupy the database until removed with
+`ops reset-telemetry` while the hub is stopped. That command preserves users,
+credentials, enrollment, settings, alert state, metadata and inventory.
 
 Collector defaults are 64 MiB logical JSON and 80 MiB physical main+WAL per hub,
 256 MiB logical and 640 MiB physical across eight destinations. Physical pressure

package/docs/system-installation.md

@@ -31,7 +31,8 @@ The installed `rigscope system` command and `dist/system.cjs` use the same code.
   hub/enrollment.json                  rigscope-hub 0600
   hub/run/hub.sock                     private Unix socket (remote mode)
   collector/state.json                 rigscope-collector 0600
-  collector/outbox/                    durable collector outboxes
+  collector/outbox/                    collector queues, durable mode only
+  machine-data-transition.json         root:root 0600, one-time machine-data transition marker
   backups/                             root:root 0700, pre-upgrade/pre-rollback SQLite copies
   system-install.json                  root:root 0600, canonical component state/versions/backups/adoption
   power-access.json                    root:root 0600, original counter modes for reversal
@@ -104,8 +105,14 @@ A pre-canonical system installation is reset, not migrated. `system install` and
 units completely, then remove the old configuration and history and install
 the canonical layout fresh. Back up `/var/lib/rigscope` first if that history
 must be kept; there is no rollback to the old format. Later upgrades that stay
-canonical keep accounts, history, settings, collector identities and pending
-samples, and rollback keeps its paired database backup.
+canonical keep accounts, settings and collector identities and rollback keeps
+its paired database backup. The first such upgrade after the RAM-first release
+also completes the one-time machine-data transition, discarding machine-derived
+history and pre-RAM-first durable collector queues once — even data previously
+opted into keeping — while preserving machine names/tags; a
+`machine-data-transition.json` marker in `/var/lib/rigscope` makes every
+subsequent upgrade preserve durable history and queues. See
+[telemetry storage](telemetry-storage.md#the-one-time-machine-data-transition).
 
 - With `--enable`, `--role local` initially enables both components.
 - With `--enable`, `--role hub` initially enables only the hub.
@@ -131,7 +138,7 @@ identity and RAPL grant. With no destination it tries the colocated hub:
   cleanly before collection until a destination is saved.
 
 Configured remote destinations and credentials are never overwritten. Re-running
-`enable collector` leaves its destination, token, identity and outboxes intact.
+`enable collector` leaves its destination, token and identity intact.
 
 ### Connecting to an independent hub