rigscope 0.0.0-stage → 0.1.0

package/ARCHITECTURE.md

@@ -0,0 +1,279 @@
+# Rigscope architecture
+
+Rigscope has one hub application process and one collector per monitored machine. This is a custom-server deployment with a production Next.js UI, not `next start` or a serverless application.
+
+## Topology and ownership
+
+- Install one collector per monitored machine.
+- Each collector opens one outbound connection to each configured hub.
+- A hub receives many collector connections and serves many authenticated browsers.
+- Browsers connect to a hub; they need no direct access to collectors.
+- Monitor the hub's machine by installing a collector there using the same protocol.
+- Each hub owns enrollment, permissions, retention, alerts, and users independently.
+  Two hubs do not imply replicated databases or an automatic failover cluster.
+- Multiple destinations are supported from the first collector implementation. Hub
+  federation, automatic discovery, and clustered hub deployments are separate requirements.
+
+Only collector-to-hub and browser-to-hub reachability is necessary. LAN, Tailscale,
+and ordinary routed networks use the same protocol. No collector-to-collector links
+or inbound collector ports are required.
+
+## Transport choices
+
+| Link / operation | Transport | Reason |
+| --- | --- | --- |
+| Collector ↔ hub | WebSocket over TLS (`wss://`) | One outbound session carries telemetry, acknowledgments, capabilities, and detail requests in both directions. |
+| Hub → browser, live updates | SSE over HTTPS | Predominantly one-way updates; EventSource provides reconnects and event IDs. |
+| Browser → hub, queries/actions | HTTPS JSON requests | Normal request/response semantics for history, settings, authentication, and explicit actions. |
+| Collector enrollment | HTTPS JSON request | Exchange a short-lived enrollment token for a credential specific to that hub connection. |
+
+WebSocket keeps acknowledgments and on-demand detail requests on the collector's existing outbound connection. Browser SSE and JSON requests keep live updates separate from explicit queries. Bounded JSON frames have no automatic transport fallback.
+
+## Runtime and module boundaries
+
+Keep TypeScript/Node and Next.js, with two executable roles: `collector` and `hub`.
+The hub has one explicit, long-running Node entry point that owns its HTTP server,
+WebSocket upgrades, application services, and background jobs. It delegates UI requests to
+Next.js. This preserves one hub application process/listener; a TLS proxy is optional
+infrastructure. Collection belongs to the collector and continues without a browser.
+
+Transport handlers receive services from the composition root. Do not assume a `globalThis`
+object is shared between Next.js bundles or let route requests start monitoring loops.
+This is a custom-server deployment, not unchanged `next start` or a serverless deployment.
+The entry point has its own runtime bundle. Production ships `.next` with `dist/*.cjs`; development uses `.next-dev`. Collector upgrades go to `/api/collector/connect`; framework upgrades reach Next.js.
+
+Module layout (responsibilities; consult the source tree for exact paths):
+
+```text
+collector/
+  main.ts                  # lifecycle and local configuration
+  sampling/                # OS metrics, capabilities, monotonic rate calculation
+  destinations/            # independent delivery session/outbox per hub
+src/
+  contracts/               # wire schemas, units, identifiers
+  hub/
+    main.ts                # composition root; HTTP + upgrades + Next.js
+    enrollment/            # credentials and hub-local machine mapping
+    telemetry/             # validation, persistence, latest state, freshness
+    subscriptions/         # browser interests -> expiring detail requests
+    history/               # SQLite batches, queries, retention, rollups
+    alerts/                # incident lifecycle and notifications
+    transport/             # WebSocket, SSE, and HTTP handlers
+  app/                     # fleet and machine-scoped UI
+  components/              # existing visual system
+```
+
+Keep substantial behavior behind small module interfaces. Telemetry accepts batches,
+returns state/history, and provides subscriptions; callers do not manage its deduplication
+or freshness. Destination delivery hides reconnects/acks/outboxes from sampling. Sampling
+hides OS/tool differences. Do not add generic interfaces for hypothetical implementations;
+wire contracts are a real process boundary already.
+
+### Installation and component lifecycle
+
+One release contains the hub, collector, UI and administration tools. The install
+role is an initial preset; version 2 configuration records independent hub and
+collector enablement. Version 1 roles are mapped in memory on read and migrated
+on an explicit mutation. Read-only status never rewrites configuration or units.
+
+User installations have separate hashed hub and collector systemd units, each
+running `rigscope run hub|collector` with its own supervisor lease. System scope
+uses separate dedicated accounts and hardened units. Neither service depends on
+the other. Each retains its settings, credentials and data when disabled; a
+collector can continue sending to remote hubs while its local hub is disabled.
+An unconfigured collector reports Awaiting connection and stays dormant.
+
+The configuration module owns presets, migration and component setup. The service
+module owns systemd control and component service registration. The lifecycle
+module starts and verifies selected components. Upgrade and rollback coordinate
+one shared runtime, hold both component leases, back up hub storage and restore
+the exact previous activity and startup settings. Uninstall removes both units,
+launcher and runtime copies while retaining application data.
+
+Automatic colocated pairing uses bootstrap configuration only before the first
+hub start. Once SQLite owns the registry, pairing uses that registry and the
+normal enrollment endpoint to update a live hub without restarting it. Existing
+collector destinations are preserved. Explicit `connect` also supports a
+one-time grant from another machine's hub. The [installation guide](docs/installation.md) describes component commands and hub-first setup.
+
+The implemented coordination boundaries are:
+
+- `src/live/machine-selection.ts` resolves route, authorized Fleet and remembered
+  selection with view-specific fallbacks, and coordinates navigation and persistence.
+  Views consume the selection; explicit missing Machines retain their access outcome.
+- `src/hub/sample-ingestion.ts` authenticates Sample identity against the current
+  Collector session, commits through `TelemetryStore`, then publishes eligible live
+  Samples and Incident observations only while that session remains current. It also
+  restores persisted metrics, cadence, inventory and metadata at startup without
+  marking a Collector connected. Transport formats acknowledgments from its outcomes.
+- `collector/destinations/connection.ts` owns each Hub connection's sharing policy,
+  cadence, recovered queue sanitation, inventory and durable append-before-send path.
+  Collector runtime fans shared Samples out to these connections. Sampling, GPU
+  polling, aggregate disk budgets and cross-Hub Detail scheduling remain shared.
+  Recovery applies privacy filtering without reapplying capture-time cadence.
+
+## Identity, enrollment, and messages
+
+Generate a persistent collector installation ID locally. Enroll it separately with each hub,
+which maps the authenticated collector to a hub-local machine ID. Addresses/hostnames are
+metadata. Reinstall/replacement needs explicit enrollment or administrator reassociation;
+cloned installations must generate new identities.
+
+Each hub connection has an independent credential and local sharing policy. Verify the
+hub's TLS certificate using ordinary certificate trust. Send credentials in an authorization
+header, not a URL. Remote connections require TLS; loopback-only development may explicitly
+use plaintext. Authenticate first and reject conflicting claimed collector identities.
+
+JSON message families:
+
+- `hello` / `welcome`: capabilities, inventory, hub/session identity.
+- `samples` / `ack`: bounded batches; identify exactly which sample IDs were durably accepted
+  or permanently rejected.
+- `detail.subscribe` / `detail.cancel` / `detail.result`: scoped, temporary monitoring detail.
+- `heartbeat`, `collector.status`, `gap`: connection liveness, collection errors, and
+  monitoring intervals lost to delivery limits.
+
+Sample fields: `collectorId`, `runId`, `sequence`, `bootId`, `capturedAt`,
+`kind`, and validated `payload`. `runId` changes on collector restart; `bootId` identifies
+an OS boot. `(collectorId, runId, sequence)` is unique, with sequence increasing across
+sample kinds within a run. Each hub assigns `receivedAt` and its own browser-stream cursor.
+Use stable resource IDs where possible, e.g. GPU UUID, not display order. Define units/CPU
+normalization and calculate rates from local monotonic elapsed time.
+
+Separate inventory, periodic metrics, and process detail. Unsupported/failed metrics have
+explicit status and absent values, never successful zeroes. Process detail is live/on
+demand and is not persisted by default.
+
+## Multiple hubs and subscription policy
+
+Collect each metric once at the fastest locally permitted requested cadence, then fan it
+out to authorized connections. Apply per-destination field filters and cadence before
+queueing/transmission. Omit process arguments and environment variables by default. Hubs
+cannot install destinations, change another destination's policy, or exceed local budgets.
+If a destination's sharing policy is reduced, cancel disallowed subscriptions and purge
+now-forbidden fields from its pending queue before further transmission.
+
+Each destination owns its session, bounded queue, acknowledgment state, and reconnect
+schedule. An offline hub must not block a healthy hub or sampling. Set a configurable
+destination count and global resource budget as well as per-destination limits.
+
+Example: A needs GPU summaries; B needs summaries and has someone viewing Processes. Share
+one GPU collection pass, deliver process detail only to B, and stop extra scans when its
+subscription expires. A's subscription must not authorize sensitive delivery to B.
+
+## Failure, delivery, and overload
+
+- WebSocket ordering applies within a connection, not across reconnects. Use heartbeats,
+  idle deadlines, and exponential reconnect backoff with jitter.
+- Periodic metrics use at-least-once delivery within the retention budget. Retry retained samples until acked;
+  deduplicate in the hub transaction. Ack after durable commit, not socket receipt. Reject
+  invalid records explicitly so bad samples cannot retry forever. Process results are
+  transient and request-scoped.
+- Use disk-backed per-hub outboxes for periodic metrics to recover across collector restarts.
+  Bound age/bytes per destination and total disk usage. Default caps: 10 minutes / 64 MiB
+  per destination, whichever comes first; measure before finalizing. Evict oldest pending
+  telemetry at the cap and retain a bounded, coalesced gap notice. Bound the in-flight
+  window too. Do not spool sensitive process detail by default.
+- Prioritize fresh metrics over rate-limited backfill. Backfill fills history but cannot
+  replace newer live state or trigger an old incident as if it just happened.
+- Bound frames, ingestion rates, outstanding requests, and browser buffers. WebSocket does
+  not supply application delivery guarantees. Coalesce metric updates for a slow browser
+  or disconnect/resynchronize it; refetch incident state after gaps.
+- Track connection health separately from sample freshness: a connected collector can
+  have broken GPU collection. Use expected cadence and receipt time for liveness; retain
+  capture time and flag clock skew rather than trusting remote wall clocks.
+- Removing a destination stops delivery and purges its credential/outbox. Hub revocation
+  terminates existing sessions as well as rejecting new ones.
+
+## Browser flow
+
+Use one authorized, multiplexed SSE stream per open app tab for its machines/event types,
+not one per chart or machine. Prefer HTTP/2 at the TLS proxy because HTTP/1.1 browsers limit
+concurrent SSE connections per origin. Disable proxy buffering for streams and configure
+WebSocket upgrades/idle timeouts end to end.
+
+Authenticate with same-origin secure, HttpOnly session cookies. Authorize scope on connect,
+replay, and permission changes; protect mutations against CSRF. Filter before transmission.
+Establish a consistent initial subscription/snapshot boundary, then emit updates. Provide
+event IDs and bounded replay. Expired cursors or a previous hub run cause a reset/fresh
+snapshot. EventSource reconnects do not themselves provide durable replay. History queries
+use HTTPS with a point/result budget and suitable rollups.
+
+Opening an authorized detail view creates/renews a bounded lease over the collector's
+existing WebSocket. The hub combines equivalent viewer interests; the collector combines
+compatible interests across hubs while preserving delivery permissions. Expire leases
+using local monotonic TTLs. Browser disconnect, hub disconnect, or renewal failure releases
+extra work promptly. Requests must fit local policy and reported capabilities.
+
+## Storage and scale
+
+Each hub owns a SQLite database, one bounded write queue, batched writes, retention, and
+rollups that preserve min/max. Never scan the OS or write telemetry once per browser.
+Bound query/transaction work. Measure event loop delay during ingestion, history queries,
+retention and rendering; move synchronous database work to a worker thread if needed.
+
+One hub application instance owns connection registry, leases, latest state, and bounded
+browser replay. Many connections do not require multiple backend replicas. Replicas later
+need explicit session routing, pub/sub, shared storage, and background-job ownership.
+
+Historical planning envelope: 1–50 machines with multiple viewers, not a measured capacity
+claim. There is no fixed machine-count limit. The concurrent collector socket budget
+defaults to 100 and is configurable with `HUB_MAX_COLLECTOR_CONNECTIONS`; it is a
+deployment resource budget, not enrollment capacity. Benchmark representative payload
+sizes, process counts, subscriptions, viewers, history queries and host resources.
+Observe queue depth, stream count, active leases,
+ingestion lag, dropped samples, memory, and event loop delay.
+
+## Future actions
+
+The release is read-only. Future structured actions travel browser HTTPS →
+hub authorization/audit → collector WebSocket → result → hub → browser SSE. Each destination
+has an explicit action policy, default denied. Read-only hubs may request allowed monitoring
+detail. Initially allow at most one mutating hub per collector to avoid conflicting control.
+
+Actions need request IDs, deadlines, handling of ambiguous outcomes after connection loss,
+and execution-time target validation (machine/boot/PID/start identity for processes).
+Do not apply telemetry retry behavior to destructive actions. Specify action semantics
+separately before implementing kill/renice or service restarts.
+
+## Terminology
+
+**Machine**:
+A physical server or virtual machine whose operating system and workloads are monitored.
+_Avoid_: Node (when it means the monitored machine)
+
+**Collector**:
+The background service installed on a machine to gather its monitoring information and report it to configured hubs.
+_Avoid_: Agent, AI agent, sensor, exporter (for this service)
+
+**Hub**:
+An independently operated monitoring service that receives information from collectors and makes it available to its users.
+_Avoid_: Primary (unless an explicit primary relationship exists)
+
+**Hub connection**:
+A collector's independently configured relationship with one hub, including what information that hub may receive and what requests it may make.
+_Avoid_: Replica, mirror (independent hubs do not imply replicated state)
+
+**Fleet**:
+The collection of machines a user can view through a particular hub.
+
+**Browser session**:
+A user's authenticated access to one independently operated hub.
+
+**Machine scope**:
+The set of machines a user is permitted to view through a hub. An empty scope grants no machine access.
+
+**Sample**:
+A measurement of a machine or resource at a particular time.
+
+**Capability**:
+A category of monitoring information or permitted operation that a collector can provide for a particular hub connection.
+
+**Detail subscription**:
+A temporary request for more detailed monitoring information about selected resources.
+
+**Incident**:
+A tracked occurrence of an alert condition, including its active and resolved states.
+
+
+See [operations](docs/operations.md) for persistence, upgrade and recovery guarantees.

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Release notes
+
+## 0.1.0
+
+Initial public release of Rigscope, a self-hosted Linux system and process monitor.
+
+- Fleet and machine views with CPU, memory, swap, GPU, disk and network readings.
+- Durable History, per-core charts, live process inspection and CSV/JSON exports.
+- Threshold and availability alerts, HTTPS webhooks, users and machine scopes.
+- Outbound collectors with independent sharing and durable retry queues for up to
+  eight hubs per collector.
+- Managed user installation, independent hub/collector services, enrollment,
+  diagnostics, verified upgrades, rollback and offline password recovery.
+- Optional system installation with dedicated unprivileged service accounts and
+  narrowly scoped CPU package-energy access.
+
+Requires Linux and Node.js 26+. Background user installation requires systemd.
+NVIDIA and available AMD GPU counters are supported; Intel sensors are partial.
+Missing or inaccessible readings remain unavailable. Remote process mutation,
+hub federation and clustering are outside this release.
+
+See [installation](docs/installation.md) for hardware limits and
+[scale validation](docs/scale-validation.md) for measured synthetic workloads.
+Internal configuration, database and wire-protocol revisions are independent of
+the application version.

package/DESIGN.md

@@ -0,0 +1,299 @@
+---
+name: Rigscope
+description: A calm remote monitoring console with clear hierarchy, useful density, and coherent dark/light themes.
+colors:
+  background: "#1a1b1e"
+  card: "#26272b"
+  card-strong: "#2d2e33"
+  border: "#3a3b3f"
+  foreground: "#e4e5e8"
+  muted-foreground: "#a2a4a9"
+  accent: "#3584e4"
+  accent-foreground: "#ffffff"
+  selected: "#1e3a5c"
+  ok: "#3db84a"
+  ok-soft: "rgba(61, 184, 74, 0.15)"
+  warn: "#e5a83b"
+  warn-soft: "rgba(229, 168, 59, 0.15)"
+  crit: "#e05e5e"
+  crit-soft: "rgba(224, 94, 94, 0.15)"
+  cpu: "#3584e4"
+  mem: "#4ec289"
+  swap: "#d8a23a"
+  scrollbar: "#3a3b3f"
+typography:
+  page-title:
+    fontFamily: "system-ui, ui-sans-serif, 'Noto Sans', 'Inter', sans-serif"
+    fontSize: "1.125rem"
+    fontWeight: 600
+    letterSpacing: "-0.025em"
+  panel-title:
+    fontFamily: "system-ui, ui-sans-serif, 'Noto Sans', 'Inter', sans-serif"
+    fontSize: "0.875rem"
+    fontWeight: 500
+    letterSpacing: "-0.025em"
+  nav:
+    fontFamily: "system-ui, ui-sans-serif, 'Noto Sans', 'Inter', sans-serif"
+    fontSize: "0.875rem"
+    fontWeight: 400
+    letterSpacing: "-0.025em"
+  support:
+    fontFamily: "system-ui, ui-sans-serif, 'Noto Sans', 'Inter', sans-serif"
+    fontSize: "0.75rem"
+    fontWeight: 400
+    lineHeight: 1.5
+  data:
+    fontFamily: "system-ui, ui-sans-serif, 'Noto Sans', 'Inter', sans-serif"
+    fontSize: "1.25rem"
+    fontWeight: 600
+    fontFeature: "tabular-nums"
+    letterSpacing: "-0.025em"
+rounded:
+  panel: "12px"
+  row: "8px"
+  control: "6px"
+  pill: "9999px"
+spacing:
+  panel: "20px"
+  section: "20px"
+  page: "24px"
+  rail: "56px"
+components:
+  panel:
+    backgroundColor: "{colors.card}"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.panel}"
+    padding: "20px"
+  panel-title:
+    textColor: "{colors.foreground}"
+    typography: "{typography.panel-title}"
+  empty-state:
+    backgroundColor: "transparent"
+    textColor: "{colors.muted-foreground}"
+    rounded: "{rounded.row}"
+    padding: "40px 24px"
+  nav-link-selected:
+    backgroundColor: "{colors.selected}"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.row}"
+    padding: "8px 10px"
+  nav-link:
+    backgroundColor: "transparent"
+    textColor: "{colors.muted-foreground}"
+    rounded: "{rounded.row}"
+    padding: "8px 10px"
+  theme-toggle:
+    backgroundColor: "transparent"
+    textColor: "{colors.muted-foreground}"
+    rounded: "{rounded.control}"
+    size: "36px"
+---
+
+# Design System: Rigscope
+
+## Overview
+
+**Creative North Star: "The Rig-as-Console"**
+
+A calm, modern monitoring console inspired by KDE's system monitor: clear resource
+readouts, useful density, restrained surfaces, and charts that make changes easy to see.
+The same visual language should support a single GPU rig and a fleet of servers.
+
+This document provides direction and starting values. The frontmatter records the current
+shared tokens; it does not freeze the palette, type scale, layout, or component inventory.
+Existing CSS is the source for shipped values. Extend shared tokens coherently when a
+new view needs them and update this record when those choices become reusable.
+
+Prioritize accurate data, legibility, accessibility, and understandable interaction.
+Specific styling choices below can evolve through normal implementation judgment; a
+useful table, larger heading, additional surface, or new component needs no special approval.
+
+**Key Characteristics:**
+- Clear hierarchy and scan-friendly data, with room for both dense and spacious views.
+- Quiet neutral surfaces, purposeful color, and recognizable metric/state meanings.
+- Dark and light themes treated as full peers.
+- Consistent components where tasks repeat; specialized presentation where tasks differ.
+- Honest loading, empty, stale, unavailable, error, and disconnected states.
+
+## Colors
+
+Begin with the current neutral palette and blue accent. Reuse semantic tokens for common
+roles so both themes stay coherent. The palette can expand to support new interactions,
+alerts, chart series, hierarchy, and accessible contrast.
+
+- **Primary:** accent for important actions, selection, focus, and useful emphasis. Filled
+  buttons, selected surfaces, and small brand treatments are allowed when they clarify hierarchy.
+- **Neutral:** background/card/card-strong and foreground/muted-foreground are the starting
+  vocabulary. Add stronger dividers, intermediate text, or additional surfaces when needed;
+  there is no limit of two text colors or one border strength.
+- **State:** healthy, warning, critical, informational, unknown and offline states should be
+  recognizable through labels/icons as well as color. Distinguish unavailable from healthy.
+- **Metrics:** CPU blue, memory green, and swap amber are current defaults. Keep mappings
+  predictable within and across related views; add distinguishable GPU/resource series and
+  legends. A deliberate accessible palette update can revise defaults consistently.
+
+Choose colors against their actual background in both themes. A token name alone does
+not guarantee contrast. New reusable roles belong in the theme rather than scattered
+component literals; exploratory values can be promoted once the design settles.
+
+## Typography
+
+System sans is the starting family for familiar, quick-loading UI. The existing page
+heading (18px), panel heading/body (14px), supporting text (12px), and gauge value (20px)
+are examples from the scaffold, not a required scale or a maximum size.
+
+Use whatever hierarchy makes the task clear. Fleet summaries may need larger readouts;
+dense tables may need compact labels; setup and error explanations need comfortable prose.
+Use meaningful heading order, adequate line height, and wrapping that survives narrow
+viewports and zoom. Do not shrink essential information to preserve a layout.
+
+Use tabular numerals for aligned/changing measurements. Monospace is appropriate for
+commands, addresses, identifiers, or logs when it improves reading. Include units and
+consistent precision; stable text/column placement matters more than a particular class.
+
+## Layout
+
+Design for the information and the user's task. The current sidebar, header, and scrolling
+main region are a useful baseline. Navigation, sidebar width, scrolling behavior, and
+breakpoints may evolve as fleet, machine, settings and investigation views become real.
+
+All pages render inside one shared content container owned by `AppShell`: centered,
+capped at 1500px, with the standard page padding — page code adds no extra max-width or
+centering wrappers. Workspace pages (Processes) fill the same container's full height.
+Card grids that may hold a single item use auto-fit tracks so one card spans the row
+instead of stranding beside empty columns.
+The scaffold uses 20px panel gaps/padding and 24px page padding. Treat these as comfortable
+defaults. Add compact/comfortable density, smaller mobile gutters, wider investigation
+layouts, or other spacing when appropriate. Reuse shared spacing choices once established.
+
+Tables, lists, charts, grouped sections, toolbars, and split views are valid building blocks.
+A fleet table does not need a ring-gauge card for every machine, and every region does not
+need a bordered panel. Use grouping and alignment before adding containers. Keep reading
+order, reachable controls and critical status clear across screen sizes. Horizontal
+scrolling can be appropriate for a dense table; contain it within that surface.
+
+## Elevation & Depth
+
+Prefer the existing quiet surfaces and subtle borders as the default. Tonal differences,
+stronger dividers, subtle shadows, or a combination can establish hierarchy. Menus, dialogs,
+popovers, and other overlays may need elevation to remain distinct from the data behind them.
+
+There is no global ban on shadows, gradients, or additional layers. Use them selectively,
+keep both themes readable, and avoid overwhelming chart marks or making ordinary data
+panels appear interactive. Focus indicators can use the most visible accessible treatment.
+
+## Shapes
+
+The current 12px panel, 8px row, and 6px control radii provide a coherent starting family.
+They are defaults, not mandatory dimensions. Tables can have square edges; compact tools,
+chips, overlays, and new containers can choose shapes suited to their job.
+
+Use circles for meaningful gauges/status marks where useful. Rings are an available
+visualization, not a required signature for every metric. Choose charts and marks based
+on what people need to compare.
+
+## Components
+
+### Existing foundations
+
+`Panel`, `EmptyState`, `AppShell`, navigation, and theme toggle are reusable starting points.
+Reuse them when they fit. Add variants or new components when that produces a clearer
+interface; avoid forcing every view through `Panel` and `EmptyState`.
+
+Current component dimensions and styles are examples of the shipped scaffold. A new
+component should share the broader visual language and interaction conventions without
+copying every measurement.
+
+### Data and connection states
+
+Separate first load, empty results, unsupported metrics, permission failure, stale samples,
+collector disconnect, and hub disconnect. Keep last-known values visible when useful,
+with an explicit timestamp/state. A missing metric must not look like successful zero usage.
+
+Dashed placeholder rings belong to the current development scaffold. Future empty/loading
+states can use contextual explanations, skeletons, compact inline states, and appropriate
+next actions. Avoid presenting an unavailable control as a working action.
+
+### Interactions and motion
+
+Give controls understandable labels and relevant hover, focus, selected, disabled, loading,
+and error feedback. Preserve keyboard access and accessible names when labels collapse.
+Use familiar controls for filters, time ranges, enrollment, settings and confirmations.
+
+Brief transitions can clarify changes and make the interface feel responsive. Existing
+color transitions are a baseline; expansion, movement and other feedback are allowed when
+useful. Honor reduced-motion preferences and keep frequent metric updates stable enough
+for reading and selection.
+
+Process tables fill the available workspace and preserve column proportions during live
+updates and browser resizing. Minimum readable widths trigger scrolling inside the table;
+the toolbar stays visible and table headers remain pinned while rows scroll. Drag column dividers to resize, use arrow keys on a focused
+divider, or double-click to reset. View mode, per-table sorting and widths persist in the
+browser; search, expanded applications, pause and machine selection last for the tab session.
+Machine selection is shared across Fleet, Overview, History and Processes for the tab.
+The sidebar keeps Fleet as the parent of a single machine selector and indented
+Overview/History/Processes links. Global hub pages follow in a separate group. Header
+breadcrumbs show Fleet / machine / view; page-level tabs and pickers are omitted. Fleet
+rows show compact CPU/memory trends received since sign-in. Overview combines CPU/GPU
+and RAM/VRAM into two charts in one fixed ten-minute panel. History owns range and metric
+selection for detailed investigation. Its picker groups CPU, memory, GPU, storage and
+network controls, keeping core/card selection inside the relevant group. Global Select all / Unselect all share the Metrics disclosure row;
+per-resource All / None actions update metric selection in one operation, respecting
+machine capabilities and the hub's recorded metric catalog. Automatic history polling
+leaves Refresh visually unchanged; manual refresh alone disables and animates it until
+the request settles. Resource
+sections fill the content width; related charts share a row on desktop and stack on
+phones. CPU usage, I/O wait and CPU pressure share a percentage chart, while temperature
+and power retain separate units. RAM and filesystem capacity each use one chart with
+a Bytes / % switch when both stored metrics are selected; unit choices persist per
+machine and visible exports follow the displayed unit. Swap belongs in the Memory
+section. Recent usage legends number GPU cards to distinguish identical models. Collector diagnostics remain behind a bounded disclosure;
+obvious explanatory copy is omitted, including on sign-in.
+
+Live sampling, process updates and visible-tab history refreshes default to one second.
+Refresh requests never overlap or replace existing charts with loading panels. Process
+freshness changes update the status indicator without adding a banner or moving the table.
+
+Per-core History defaults to all available cores, with an explicit All cores / None
+and a scrollable checkbox picker for custom subsets. Up to eight series use lines;
+larger selections use a scrollable heatmap of stored bucket peaks, with latest/peak
+values and optional busiest-first order. Missing readings remain unfilled; recorded
+gaps mask the heatmap. Requests allow the collector contract's 1024 cores while
+retaining the existing scan/time budgets and partial-result indicators.
+
+History retains its time range and per-machine metric, GPU-card and series visibility
+choices in the browser; its machine, control expansion and auto-refresh state last for the tab.
+Returning to Processes keeps the last snapshot visible while fresh data is requested.
+Snapshots stay in memory, are scoped to the browser login, and show their freshness state.
+
+## Do's and Don'ts
+
+### Do:
+- **Do** choose the layout and density that help people answer the monitoring question.
+- **Do** reuse or extend shared tokens/components when the behavior or role repeats.
+- **Do** preserve units, freshness, explicit states, and consistent metric meanings.
+- **Do** verify keyboard behavior, zoom, contrast, and both themes when changing UI.
+- **Do** evolve this guidance when a better reusable pattern emerges.
+
+### Don't:
+- **Don't** treat scaffold dimensions or examples as permanent product requirements.
+- **Don't** force every screen into the same cards, chart types, or scrolling structure.
+- **Don't** rely on color alone for status, selection, or chart interpretation.
+- **Don't** show stale/unavailable data as healthy live measurements or fake interactivity.
+- **Don't** sacrifice legibility or access to controls to preserve a visual convention.
+
+## Release setup
+
+Rigscope retains the established console styling. Fleet and Connections expose an
+admin-only Add machine action that links to the collector enrollment section. Generated
+commands use the current hub origin, and prompt privately for the separate, one-time
+grant. Copy controls have visible status and a manual-selection fallback. Enrollment
+adds no live-state banners above monitoring data.
+
+## Product and identity
+
+Rigscope is a self-hosted Linux resource/process monitor for a machine owner or small-fleet operator. Each collector connects outbound to independently operated hubs; each hub owns its users, permissions and history. The main tasks are spotting stale/unhealthy machines, inspecting resource history and opening live process detail. Remote mutating process actions are outside this release.
+
+App surfaces use Operate mode: precise data, quiet surfaces, stable live updates and familiar controls. Freshness changes update existing status indicators without inserting banners above data. Interface copy consists of labels, values and actionable errors; omit redundant explanatory paragraphs.
+
+The identity is an open rack frame around a rising trace and two sample points. `BrandMark` is the shared, decorative 24-unit SVG in the sidebar and sign-in row; the neighboring Rigscope text/link provides its accessible name. The app icon uses the same geometry with a dark backing and bright blue stroke for light/dark browser chrome. It is legible at 16–32px, with no animation, raster assets or layout changes. Keep this small brand gesture separate from metric semantics.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Triet (@Triet1402)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.