refactor: rename Metrics gear URL /history → /metrics; clarify the term

The Metrics gear was historically called "history" because the page
shows time-series data. That name leaked into the URL (/history), the
API endpoints (/api/{boxID}/history/*), the templ file
(history.templ), the handler functions (HistoryPage,
APIStatsHistoryHandler, …), and assorted comments / docs / README
entries. With nginx / Apache / Caddy / Traefik detection now landing
(issue #95) and "metric source" / "primary source" terminology in the
new code, the dual naming has become genuinely confusing.

This commit renames the metrics-gear identity end-to-end:

- Page route: /history → /metrics (plugin.go SidebarItem.Path,
  base.templ path-prefix match + sidebar links, gears-page.js).
- API routes:
  /api/{boxID}/history/stats             → /api/{boxID}/metrics/stats
  /api/{boxID}/history/metrics           → /api/{boxID}/metrics/system
  /api/{boxID}/history/backend/{name}    → /api/{boxID}/metrics/backend/{name}
  (Last one coexists with /metrics/backend/{name}/details — the
  time-series endpoint vs the drill-down details endpoint added in #87.)
- Handler functions:
  HistoryPage                  → MetricsPage
  APIStatsHistoryHandler       → APIMetricsStatsHandler
  APIBackendHistoryHandler     → APIMetricsBackendHandler
  APISystemMetricsHistoryHandler → APIMetricsSystemHandler
- File: pages/history.templ → pages/metrics.templ
  (templ component History() → Metrics())
- JS callers: history.templ + details.templ + chart_partials.templ
  (8 fetch() URLs updated).
- Docs: metrics gear README routes table + architecture diagram +
  development snippet; cmd/server/main.go route-group comment;
  pages.go migration-history comment; permissions.go field comment;
  docs/gears.md gear list.

Intentionally **kept** as legitimate "history" concepts (per design
discussion):

- DB tables stats_history, system_metrics_history, backend_history —
  the rows ARE historical records. Renaming requires a migration with
  no user-visible benefit; the names accurately describe what they
  contain. The DB query methods that read them (GetStatsHistory,
  GetBackendHistory, GetSystemMetricsHistory) keep their names for
  the same reason.
- Snapshot interval / retention config: HistoryIntervalSeconds,
  store_history, history_retention_days — these control how the
  historical record is kept. Same reasoning.
- Local `history` variable names inside the renamed handler functions
  — they reflect what the DB methods return.
- OS-update apt/zypper/dnf/pacman history — distinct concept.
  /api/v1/system/updates/history on the agent, /os-updates/history on
  the dashboard, parseAptHistoryLog, /var/log/apt/history.log, etc.
  All untouched.
- HAProxy config change history — distinct concept.
  /{boxID}/haproxy/config/history,
  templates/pages/haproxy_config/change_history.templ, etc. Untouched.

Agent module: no changes. The agent's "history" references are all
OS-update package-manager history (apt/zypper/dnf/pacman/apk/yum),
which is the legitimate concept.

Tests + build green on both modules.

Author: sarg3nt

docs/gears.md

@@ -138,7 +138,7 @@ Client gears run in the **gearbox** web application (the monitoring client) and
 - `traffic` - Traffic analysis and visualization page
 - `alerts` - Alert management page
 - `services` - Service status and control page
-- `metrics` - System metrics and history page
+- `metrics` - Time-series system + HAProxy metrics page (`/metrics`)
 
 ### Gear Scope: Box vs System
 

gearbox/cmd/server/main.go

@@ -627,7 +627,7 @@ func main() {
 
 		// Gear-registered routes
 		// Gears handle: / (haproxy overview), /status-grid (haproxy), /logs (logs),
-		// /services (services), /history (metrics), /certificates (certificates),
+		// /services (services), /metrics (metrics gear), /certificates (certificates),
 		// /traffic (traffic), /alerts (alerts)
 		gearManager.RegisterRoutes(r)
 
@@ -676,10 +676,13 @@ func main() {
 			r.Get("/{boxID}/charts/error-rates", h.APIChartsErrorRatesHandler)
 			r.Get("/{boxID}/logs/{logName}", h.APILogsHandler)
 			r.Get("/{boxID}/log-sources", h.APILogSourcesHandler) // Get enabled log sources
-			// History API endpoints
-			r.Get("/{boxID}/history/stats", h.APIStatsHistoryHandler)
-			r.Get("/{boxID}/history/metrics", h.APISystemMetricsHistoryHandler)
-			r.Get("/{boxID}/history/backend/{backendName}", h.APIBackendHistoryHandler)
+			// Metrics gear — time-series endpoints (HAProxy stats,
+			// system metrics, per-backend stats). These power the
+			// charts on the /metrics page; the /metrics/* "v2"
+			// endpoints just below power the KPI band + insights.
+			r.Get("/{boxID}/metrics/stats", h.APIMetricsStatsHandler)
+			r.Get("/{boxID}/metrics/system", h.APIMetricsSystemHandler)
+			r.Get("/{boxID}/metrics/backend/{backendName}", h.APIMetricsBackendHandler)
 			r.Get("/{boxID}/incidents", h.APIIncidentsHandler)
 
 			// Metrics gear v2 — insights & drill-down endpoints

gearbox/internal/framework/handler/api_stats.go

@@ -102,8 +102,12 @@ func (h *Handler) APISystemMetricsHandler(w http.ResponseWriter, r *http.Request
 	h.writeJSON(w, response)
 }
 
-// APIStatsHistoryHandler returns historical stats data.
-func (h *Handler) APIStatsHistoryHandler(w http.ResponseWriter, r *http.Request) {
+// APIMetricsStatsHandler returns time-series HAProxy stats for the
+// Metrics page's per-backend chart. Served at /api/{boxID}/metrics/stats.
+// The underlying DB method is still named GetStatsHistory because the
+// data it returns IS historical records; the URL renamed for clarity
+// with issue #97.
+func (h *Handler) APIMetricsStatsHandler(w http.ResponseWriter, r *http.Request) {
 	boxID := chi.URLParam(r, "boxID")
 	if boxID == "" {
 		http.Error(w, "Server ID required", http.StatusBadRequest)
@@ -142,8 +146,12 @@ func (h *Handler) APIStatsHistoryHandler(w http.ResponseWriter, r *http.Request)
 	})
 }
 
-// APIBackendHistoryHandler returns historical data for a specific backend.
-func (h *Handler) APIBackendHistoryHandler(w http.ResponseWriter, r *http.Request) {
+// APIMetricsBackendHandler returns time-series stats for a specific
+// backend on the Metrics page. Served at
+// /api/{boxID}/metrics/backend/{backendName}. Coexists with the
+// /metrics/backend/{name}/details drill-down (which returns aggregate
+// insights rather than the time-series).
+func (h *Handler) APIMetricsBackendHandler(w http.ResponseWriter, r *http.Request) {
 	// Check if user has permission to view metrics
 	if !h.authManager.HasPermission(r, models.ComponentMetrics, models.PermissionView) {
 		http.Error(w, "Forbidden: insufficient permissions to view metrics", http.StatusForbidden)
@@ -191,8 +199,10 @@ func (h *Handler) APIBackendHistoryHandler(w http.ResponseWriter, r *http.Reques
 	})
 }
 
-// APISystemMetricsHistoryHandler returns historical system metrics.
-func (h *Handler) APISystemMetricsHistoryHandler(w http.ResponseWriter, r *http.Request) {
+// APIMetricsSystemHandler returns time-series host-level metrics for
+// the Metrics page (CPU, memory, disk, network). Served at
+// /api/{boxID}/metrics/system.
+func (h *Handler) APIMetricsSystemHandler(w http.ResponseWriter, r *http.Request) {
 	// Check if user has permission to view metrics
 	if !h.authManager.HasPermission(r, models.ComponentMetrics, models.PermissionView) {
 		http.Error(w, "Forbidden: insufficient permissions to view metrics", http.StatusForbidden)

gearbox/internal/framework/handler/pages.go

@@ -15,7 +15,7 @@ import (
 // - OverviewPage -> plugins/haproxy
 // - StatusGridPage -> plugins/haproxy
 // - LogsPage -> plugins/logs
-// - HistoryPage -> plugins/metrics
+// - MetricsPage -> plugins/metrics
 // - ServicesPage -> plugins/services
 // - CertificatesPage -> plugins/certificates
 // - TrafficPage -> plugins/traffic

gearbox/internal/framework/models/permissions.go

@@ -335,7 +335,7 @@ func GetAvailablePermissionsForComponent(c Component) []Permission {
 		}
 	case ComponentMetrics:
 		return []Permission{
-			PermissionView,      // View metrics/history page and data
+			PermissionView,      // View the Metrics page and its data
 			PermissionConfigure, // Configure metrics storage settings
 		}
 	case ComponentGears:

gearbox/internal/framework/templates/layouts/base.templ

@@ -36,7 +36,7 @@ func gearLabelForPath(path string) string {
 		return ""
 	case path == "/haproxy" || strings.HasPrefix(path, "/haproxy/"):
 		return "HAProxy"
-	case path == "/history" || strings.HasPrefix(path, "/history/"):
+	case path == "/metrics" || strings.HasPrefix(path, "/metrics/"):
 		return "Metrics"
 	case path == "/logs" || strings.HasPrefix(path, "/logs/"):
 		return "Logs"
@@ -2175,7 +2175,7 @@ func integrationPath(name string) string {
 	case "haproxy":
 		return "/haproxy"
 	case "metrics":
-		return "/history"
+		return "/metrics"
 	case "logs":
 		return "/logs"
 	case "services":
@@ -2287,7 +2287,7 @@ templ OrderedIntegrationLinks(currentPath string) {
 			@SidebarLinkWithIntegration("/haproxy", "HAProxy", SidebarIconHAProxy(), currentPath, "haproxy")
 		}
 		if canViewIntegration(ctx, "metrics") {
-			@SidebarLinkWithIntegration("/history", "Metrics", SidebarIconMetrics(), currentPath, "metrics")
+			@SidebarLinkWithIntegration("/metrics", "Metrics", SidebarIconMetrics(), currentPath, "metrics")
 		}
 		if canViewIntegration(ctx, "logs") {
 			@SidebarLinkWithIntegration("/logs", "Logs", SidebarIconLogs(), currentPath, "logs")
@@ -2332,7 +2332,7 @@ templ renderIntegrationLink(name string, currentPath string) {
 		case "haproxy":
 			@SidebarLinkDraggable("/haproxy", "HAProxy", SidebarIconHAProxy(), currentPath, "haproxy")
 		case "metrics":
-			@SidebarLinkDraggable("/history", "Metrics", SidebarIconMetrics(), currentPath, "metrics")
+			@SidebarLinkDraggable("/metrics", "Metrics", SidebarIconMetrics(), currentPath, "metrics")
 		case "logs":
 			@SidebarLinkDraggable("/logs", "Logs", SidebarIconLogs(), currentPath, "logs")
 		case "services":

gearbox/internal/framework/templates/pages/details.templ

@@ -714,7 +714,7 @@ templ BackendDetail(user *models.User, backendName string, stats *models.HAProxy
 					function loadBackendHistory() {
 						updateResolutionLabel();
 						var hours = document.getElementById('hours-select').value;
-						fetch('/api/' + backendServerID + '/history/backend/' + encodeURIComponent(backendNameVar) + '?hours=' + hours)
+						fetch('/api/' + backendServerID + '/metrics/backend/' + encodeURIComponent(backendNameVar) + '?hours=' + hours)
 							.then(function(response) { return response.json(); })
 							.then(function(result) {
 								cachedBackendData = result.data || [];

…/framework/templates/pages/history.templ …/framework/templates/pages/metrics.templgearbox/internal/framework/templates/pages/history.templ renamed to gearbox/internal/framework/templates/pages/metrics.templ gearbox/internal/framework/templates/pages/history.templ renamed to gearbox/internal/framework/templates/pages/metrics.templ

@@ -4,8 +4,8 @@ import "github.com/sarg3nt/gearbox/internal/framework/models"
 import "github.com/sarg3nt/gearbox/internal/framework/templates/layouts"
 import "github.com/sarg3nt/gearbox/internal/framework/templates/components"
 
-templ History(user *models.User, servers []models.BoxConfig) {
-	@layouts.Base("Metrics", user, "/history") {
+templ Metrics(user *models.User, servers []models.BoxConfig) {
+	@layouts.Base("Metrics", user, "/metrics") {
 		<!-- Hidden container for page header content. Title + box selector
 		     live in the global header breadcrumb + chip. -->
 		<div id="page-header-source" class="hidden">
@@ -843,12 +843,12 @@ templ History(user *models.User, servers []models.BoxConfig) {
 			await applyCapabilities(serverID);
 
 			try {
-				// Fetch stats history
-				const statsResponse = await fetch(`/api/${serverID}/history/stats?hours=${hours}`);
+				// Fetch HAProxy stats time series
+				const statsResponse = await fetch(`/api/${serverID}/metrics/stats?hours=${hours}`);
 				const statsData = await statsResponse.json();
 
-				// Fetch system metrics history
-				const metricsResponse = await fetch(`/api/${serverID}/history/metrics?hours=${hours}`);
+				// Fetch system-metrics time series
+				const metricsResponse = await fetch(`/api/${serverID}/metrics/system?hours=${hours}`);
 				const metricsData = await metricsResponse.json();
 
 				// Cache the data for fullscreen toggle

gearbox/internal/gears/metrics/README.md

@@ -1,8 +1,13 @@
 # Metrics Gear
 
-The Metrics gear surfaces historical metrics for HAProxy and the underlying
-host. It's the place users land when they want to answer *"how busy was the
-proxy, and what went wrong?"*
+The Metrics gear surfaces time-series metrics for HAProxy and the underlying
+host at the dashboard's `/metrics` URL. It's the place users land when they
+want to answer *"how busy was the proxy, and what went wrong?"*
+
+> The page used to live at `/history` and was internally referred to as the
+> "history" gear; issue #97 renamed it to `/metrics` to keep "history"
+> reserved for genuinely distinct concepts (OS-update apt/zypper history,
+> HAProxy config change history).
 
 ## Layout
 
@@ -44,7 +49,7 @@ The page has four stacked sections:
 
 | Permission          | Description                |
 |---------------------|----------------------------|
-| `metrics:view`      | View metrics and history   |
+| `metrics:view`      | View the Metrics page      |
 | `metrics:configure` | Configure metrics settings |
 
 The drill-down drawer's *Recent 5xx log lines* section additionally
@@ -53,21 +58,21 @@ shows a "logs unavailable" hint instead of failing.
 
 ## Routes
 
-| Method | Path       | Description               |
-|--------|------------|---------------------------|
-| GET    | `/history` | Main history/metrics page |
+| Method | Path       | Description       |
+|--------|------------|-------------------|
+| GET    | `/metrics` | Main Metrics page |
 
 ## API endpoints (main handler)
 
-Existing endpoints kept for backwards compatibility:
+Time-series endpoints (chart data):
 
-| Method | Path                                            | Description                   |
-|--------|-------------------------------------------------|-------------------------------|
-| GET    | `/api/{serverID}/history/stats`                 | Get historical HAProxy stats  |
-| GET    | `/api/{serverID}/history/metrics`               | Get historical system metrics |
-| GET    | `/api/{serverID}/history/backend/{backendName}` | Get backend-specific history  |
-| GET    | `/api/{serverID}/metrics/storage-stats`         | Get storage statistics        |
-| POST   | `/api/{serverID}/metrics/clear`                 | Clear metrics data            |
+| Method | Path                                            | Description                                   |
+|--------|-------------------------------------------------|-----------------------------------------------|
+| GET    | `/api/{serverID}/metrics/stats`                 | Time-series HAProxy stats (per-snapshot rows) |
+| GET    | `/api/{serverID}/metrics/system`                | Time-series host metrics (CPU/mem/disk/net)   |
+| GET    | `/api/{serverID}/metrics/backend/{backendName}` | Time-series per-backend stats                 |
+| GET    | `/api/{serverID}/metrics/storage-stats`         | Storage statistics                            |
+| POST   | `/api/{serverID}/metrics/clear`                 | Clear metrics data                            |
 
 New in v2 ("insights" surface — see `api_metrics_insights.go`):
 
@@ -87,7 +92,8 @@ default 2000) and an optional `backend` filter.
 The new endpoints sit on top of existing tables — no new collection runs
 on the agent. Specifically:
 
-- KPI summary aggregates `stats_history` (per-snapshot HAProxy stats) and
+- KPI summary aggregates `stats_history` (per-snapshot HAProxy stats — table
+  name unchanged from the pre-rename schema; the records IS historical) and
   `traffic_flows` (per-minute response-code buckets from the Traffic gear's
   collector).
 - Error Insights and backend details query `traffic_flows` exclusively —
@@ -100,16 +106,17 @@ on the agent. Specifically:
 
 ```text
 internal/gears/metrics/
-├── plugin.go             # Gear registration
-├── handlers.go           # HTTP handler (/history page)
+├── plugin.go             # Gear registration (/metrics route)
+├── handlers.go           # MetricsPage handler
 ├── partials.templ        # CPU / memory / disk / etc. widget partials
 ├── chart_partials.templ  # Reusable chart components for the home gear
 ├── icons.go              # Sidebar icon
 ├── settings.go           # Settings page component
 └── README.md             # This file
 
 internal/framework/handler/
-├── api_stats.go                       # Existing /history/* endpoints
+├── api_stats.go                       # Time-series endpoints
+│                                      # (/api/{boxID}/metrics/{stats,system,backend/*})
 ├── api_metrics_insights.go            # KPI / error breakdown / drill-down / log-errors
 └── api_metrics_insights_helpers.go    # KPI math, sparkline downsampling
 
@@ -121,7 +128,7 @@ internal/framework/database/
 ## Development
 
 The gear is automatically included in the build via its `init()` function.
-After editing `history.templ`, run:
+After editing `metrics.templ`, run:
 
 ```bash
 make templ-generate && make build

gearbox/internal/gears/metrics/chart_partials.templ

@@ -28,7 +28,7 @@ script initSessionsRequestsChart(boxID string, hours int, limit int) {
 		var canvasId = 'chart-sessions-requests-' + boxID;
 
 		function loadChart() {
-			fetch('/api/' + boxID + '/history/stats?hours=' + hours + '&limit=' + limit)
+			fetch('/api/' + boxID + '/metrics/stats?hours=' + hours + '&limit=' + limit)
 				.then(function(r) { return r.json(); })
 				.then(function(json) {
 					var data = json.data || [];
@@ -84,7 +84,7 @@ script initServerHealthChart(boxID string, hours int, limit int) {
 		var canvasId = 'chart-server-health-' + boxID;
 
 		function loadChart() {
-			fetch('/api/' + boxID + '/history/stats?hours=' + hours + '&limit=' + limit)
+			fetch('/api/' + boxID + '/metrics/stats?hours=' + hours + '&limit=' + limit)
 				.then(function(r) { return r.json(); })
 				.then(function(json) {
 					var data = json.data || [];
@@ -140,7 +140,7 @@ script initCPULoadChart(boxID string, hours int, limit int) {
 		var canvasId = 'chart-cpu-load-' + boxID;
 
 		function loadChart() {
-			fetch('/api/' + boxID + '/history/metrics?hours=' + hours + '&limit=' + limit)
+			fetch('/api/' + boxID + '/metrics/system?hours=' + hours + '&limit=' + limit)
 				.then(function(r) { return r.json(); })
 				.then(function(json) {
 					var data = json.data || [];
@@ -197,7 +197,7 @@ script initMemoryUsageChart(boxID string, hours int, limit int) {
 		var canvasId = 'chart-memory-usage-' + boxID;
 
 		function loadChart() {
-			fetch('/api/' + boxID + '/history/metrics?hours=' + hours + '&limit=' + limit)
+			fetch('/api/' + boxID + '/metrics/system?hours=' + hours + '&limit=' + limit)
 				.then(function(r) { return r.json(); })
 				.then(function(json) {
 					var data = json.data || [];
@@ -252,7 +252,7 @@ script initNetworkThroughputChart(boxID string, hours int, limit int) {
 		var canvasId = 'chart-network-throughput-' + boxID;
 
 		function loadChart() {
-			fetch('/api/' + boxID + '/history/metrics?hours=' + hours + '&limit=' + limit)
+			fetch('/api/' + boxID + '/metrics/system?hours=' + hours + '&limit=' + limit)
 				.then(function(r) { return r.json(); })
 				.then(function(json) {
 					var data = json.data || [];
@@ -328,7 +328,7 @@ script initResponseTimesChart(boxID string, hours int, limit int) {
 		var canvasId = 'chart-response-times-' + boxID;
 
 		function loadChart() {
-			fetch('/api/' + boxID + '/history/stats?hours=' + hours + '&limit=' + limit)
+			fetch('/api/' + boxID + '/metrics/stats?hours=' + hours + '&limit=' + limit)
 				.then(function(r) { return r.json(); })
 				.then(function(json) {
 					var data = json.data || [];
@@ -383,7 +383,7 @@ script initErrorRatesChart(boxID string, hours int, limit int) {
 		var canvasId = 'chart-error-rates-' + boxID;
 
 		function loadChart() {
-			fetch('/api/' + boxID + '/history/stats?hours=' + hours + '&limit=' + limit)
+			fetch('/api/' + boxID + '/metrics/stats?hours=' + hours + '&limit=' + limit)
 				.then(function(r) { return r.json(); })
 				.then(function(json) {
 					var data = json.data || [];