Merge branch 'feature/dashboard-gear'

Author: sarg3nt

CLAUDE.md

@@ -159,6 +159,47 @@ TASKS.md is a **scratch pad only** — not a tracking system. The GitHub Project
 - Fenced blocks provide a copy button in the IDE
 - Never use inline code for commands the user should run
 
+## UI Conventions
+
+### Modal dialogs — never use native `confirm()`, `alert()`, or `prompt()`
+
+The base layout (`internal/framework/templates/layouts/base.templ`) renders three globally-available themed dialog components — `@ConfirmDialog()`, `@PromptDialog()`, `@AlertDialog()` — with a Promise-returning JS API. Use these instead of the browser primitives so styling, dark-mode, escape-key handling, and a11y are consistent across the app.
+
+```javascript
+// Confirmations (returns boolean)
+const confirmed = await showConfirmDialog({
+    title: 'Delete board',
+    message: 'Delete "Media"? All tiles on this board will be removed. This cannot be undone.',
+    confirmText: 'Delete board',
+    type: 'danger',           // 'warning' (default) | 'danger' | 'info'
+});
+if (!confirmed) return;
+
+// Text input (returns string|null)
+const name = await showPromptDialog({
+    title: 'New board',
+    message: 'What should this board be called?',
+    placeholder: 'Media',
+    defaultValue: '',
+});
+
+// One-button alerts (returns void)
+await showAlertDialog({
+    title: 'Failed to delete board',
+    message: err.message,
+    type: 'error',            // 'error' (default) | 'success' | 'info'
+});
+```
+
+**Rules of thumb:**
+
+- `type: 'danger'` for destructive confirmations — gives a red button + warning icon.
+- For non-blocking failure feedback that doesn't need a button click, prefer `window.showToast(msg, level)` instead — the dialog API blocks until acknowledged.
+- All three return Promises; the calling event handler must be `async`.
+- Dialogs are already rendered into the DOM by `layouts.Base` — don't re-instantiate per-page.
+
+Existing reference usages: [user-pages/admin-user-detail.js](static/js/user-pages/admin-user-detail.js), [user-pages/profile-management.js](static/js/user-pages/profile-management.js), [haproxy_config/editor.js](static/js/haproxy_config/editor.js).
+
 ## Key Constraints
 
 ### NEVER

docs/gears.md

@@ -131,6 +131,7 @@ Client gears run in the **gearbox** web application (the monitoring client) and
 
 **Examples:**
 
+- `home` - Box-agnostic app dashboard (start page with launcher tiles, widgets, bookmarks, search)
 - `dashboard` - Main monitoring overview page (the homepage)
 - `certificates` - SSL/TLS certificate monitoring page
 - `logs` - Log viewing and analysis page
@@ -139,6 +140,26 @@ Client gears run in the **gearbox** web application (the monitoring client) and
 - `services` - Service status and control page
 - `metrics` - System metrics and history page
 
+### Gear Scope: Box vs System
+
+Most gears are **box-scoped** — they monitor a specific server, and the `gears` table holds one row per `(server_id, name)`. A few gears are **system-scoped** — they apply to the whole install, with a single row keyed by the sentinel `server_id = '__system__'`.
+
+Declare the scope on `Info`:
+
+```go
+func (g *Gear) Info() gear.Info {
+    return gear.Info{
+        Name:  "home",
+        Scope: gear.ScopeSystem, // omit or set ScopeBox for the default per-box behaviour
+        // ...
+    }
+}
+```
+
+System gears are seeded once at startup via `database.EnsureSystemGears()` (called from `cmd/server/main.go`). Box gears are seeded lazily per-server via `EnsureServerGears(boxID)` on first access, just like before. The two seeding lists are kept disjoint by construction (`DefaultGears` vs `DefaultSystemGears`).
+
+The `home` gear is the first system-scoped gear and a useful reference. Its config lives in `database.HomeConfig` and is loaded at startup via the standard `gears.config` JSON column.
+
 ### Gearbox Agent Gears
 
 Agent gears run on monitored servers (in the **gearbox-agent** application) and collect data, expose APIs, and respond to management commands.

gearbox/.gitignore

@@ -17,7 +17,9 @@ coverage.out
 coverage.html
 
 # Dependency directories
-vendor/
+# (Anchored to the module root so static/js/vendor and static/css/vendor — used
+# for vendored frontend libraries like gridstack — remain tracked.)
+/vendor/
 
 # Go workspace file
 go.work

gearbox/Makefile

@@ -1,4 +1,4 @@
-.PHONY: help build test test-coverage lint clean clean-data run dev templ-generate fmt tidy deps install-tools dev-assets
+.PHONY: help build test test-coverage lint clean clean-data run dev templ-generate fmt tidy deps install-tools dev-assets deploy deploy-build deploy-restart
 
 # Variables
 APP_NAME := gearbox
@@ -7,6 +7,14 @@ COMMIT_SHA ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
 BUILD_DATE := $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
 LDFLAGS := -ldflags "-s -w -X main.Version=$(VERSION) -X main.CommitSHA=$(COMMIT_SHA) -X main.BuildDate=$(BUILD_DATE)"
 
+# Deploy configuration — overridable on the command line:
+#   make deploy MJOLNIR_HOST=otherbox@10.0.0.99
+MJOLNIR_HOST ?= dave@10.0.0.1
+MJOLNIR_HOMELAB_PATH ?= /mnt/StormEdge/apps/homelab
+# Match the tag the homelab compose pulls so docker compose up -d picks
+# the freshly-loaded image without any compose-file edits.
+DEPLOY_IMAGE_TAG ?= ghcr.io/sarg3nt/gearbox/gearbox:dev
+
 help: ## Show this help message
 	@echo 'Usage: make [target]'
 	@echo ''
@@ -113,3 +121,37 @@ dev-assets: ## Download CDN assets locally for secure development (CSP-compliant
 	@echo ""
 	@echo "To use local assets (CSP-compliant), set in your .env:"
 	@echo "  USE_LOCAL_ASSETS=true"
+
+# ---------------------------------------------------------------------------
+# Deployment — push the local working copy to mjolnir as a Docker image,
+# bypassing the GitHub Actions registry round-trip. Useful for fast feature-
+# branch testing.
+#
+# Build target is linux/amd64 (mjolnir runs TrueNAS SCALE on x86_64).
+# Build runs through Orbstack on the dev box; no buildx setup required.
+# The image is loaded into mjolnir's Docker daemon directly via SSH, then
+# the gearbox compose stack is recreated. ~30s round trip when the layer
+# cache is warm; no public push of WIP code.
+#
+# Override on the command line: `make deploy MJOLNIR_HOST=user@host`
+# ---------------------------------------------------------------------------
+
+deploy: deploy-build deploy-restart ## Build linux/amd64 image and deploy to mjolnir (build + ship + restart)
+	@echo "✓ Deployed $(APP_NAME) ($(VERSION) / $(COMMIT_SHA)) to $(MJOLNIR_HOST)"
+	@echo "  Tail logs with:  ssh $(MJOLNIR_HOST) 'sudo docker logs -f gearbox'"
+
+deploy-build: templ-generate ## Build the linux/amd64 image and stream it to mjolnir
+	@echo "Building $(DEPLOY_IMAGE_TAG) for linux/amd64..."
+	@docker build \
+		--platform linux/amd64 \
+		--build-arg VERSION=$(VERSION) \
+		--build-arg COMMIT_SHA=$(COMMIT_SHA) \
+		--build-arg BUILD_DATE=$(BUILD_DATE) \
+		--tag $(DEPLOY_IMAGE_TAG) \
+		.
+	@echo "Streaming image to $(MJOLNIR_HOST) (gzipped over SSH)..."
+	@docker save $(DEPLOY_IMAGE_TAG) | gzip | ssh $(MJOLNIR_HOST) 'gunzip | sudo docker load'
+
+deploy-restart: ## Recreate the gearbox container on mjolnir using the homelab compose file
+	@echo "Recreating gearbox container on $(MJOLNIR_HOST)..."
+	@ssh $(MJOLNIR_HOST) 'sudo docker compose -p gearbox -f $(MJOLNIR_HOMELAB_PATH)/apps/gearbox/docker-compose.yml up -d'

gearbox/README.md

@@ -29,6 +29,7 @@ A modern, self-contained monitoring dashboard for HAProxy reverse proxy servers.
 - 📊 **Real-time Performance Metrics** - Live HAProxy statistics, throughput, and connection monitoring
 - 🔍 **Configuration-Aware** - Understands custom haproxy-autoconfig labels and displays full backend configuration
 - 🎯 **Multi-Server Support** - Monitor multiple HAProxy instances from a single dashboard
+- 🏠 **Home Dashboard Gear** - Drag-and-drop start page with launcher tiles, live widgets (Sonarr / Radarr / Plex / UniFi / Pi-hole / qBittorrent / …), inline sparkline graphs, server-side reachability checks, and encrypted per-tile API keys. See [Home gear docs](docs/home-gear.md).
 - 📱 **Mobile-Responsive UI** - Modern, beautiful interface that works on desktop, tablet, and mobile
 - 🔐 **Secure Authentication** - Session-based authentication with encrypted cookies
 - 📈 **System Metrics** - CPU, memory, disk, and network usage from HAProxy servers
@@ -290,9 +291,10 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed architecture docum
 
 ## Documentation
 
-- [SETUP.md](docs/SETUP.md) - Detailed setup instructions
-- [ARCHITECTURE.md](docs/ARCHITECTURE.md) - System architecture and design
-- [API.md](docs/API.md) - Internal API documentation (if applicable)
+- [docs/home-gear.md](docs/home-gear.md) - Home dashboard gear: widgets, sparklines, security model
+- [docs/development.md](docs/development.md) - Local development guide
+- [docs/local-development-csp.md](docs/local-development-csp.md) - CSP notes for local dev
+- [internal/gears/home/README.md](internal/gears/home/README.md) - Home gear: implementation reference (routes, schema, providers)
 
 ## Contributing
 

gearbox/cmd/server/main.go

@@ -33,6 +33,7 @@ import (
 	_ "github.com/sarg3nt/gearbox/internal/gears/alerts"
 	_ "github.com/sarg3nt/gearbox/internal/gears/certificates"
 	_ "github.com/sarg3nt/gearbox/internal/gears/haproxy"
+	_ "github.com/sarg3nt/gearbox/internal/gears/home"
 	_ "github.com/sarg3nt/gearbox/internal/gears/logs"
 	_ "github.com/sarg3nt/gearbox/internal/gears/metrics"
 	_ "github.com/sarg3nt/gearbox/internal/gears/services"
@@ -80,6 +81,13 @@ func main() {
 		"path", cfg.DatabasePath,
 		"retention_hours", cfg.DatabaseRetentionHours)
 
+	// Seed default rows for system-wide gears (e.g. the Home dashboard).
+	// Box-scoped gears are seeded lazily on first access; system gears
+	// have no box to attach to, so we seed them once here.
+	if err := db.EnsureSystemGears(); err != nil {
+		logger.Error("failed to seed system gears", "error", err)
+	}
+
 	// Ensure admin user exists
 	var adminPassword string
 	var adminPasswordHash string
@@ -355,6 +363,7 @@ func main() {
 
 	// Create gear dependencies
 	authAdapter := services.NewAuthAdapter(authManager)
+	authAdapter.SetEncryptor(encryptor)
 	eventsAdapter := services.NewEventsAdapter(eventHub)
 	serverAdapter := services.NewServerAdapter(db, encryptor, servers, logger)
 
@@ -503,6 +512,10 @@ func main() {
 		// Logout
 		r.Post("/logout", h.Logout)
 
+		// Root URL — redirect to the user's default-landing-path
+		// (per-user → system → fallback). See feature/dashboard-gear F1.
+		r.Get("/", h.RootRedirect)
+
 		// Settings routes
 		r.Route("/settings", func(r chi.Router) {
 			// Settings menu page (accessible by all authenticated users)

gearbox/docs/home-gear.md

@@ -0,0 +1,119 @@
+# Home Gear (Dashboard)
+
+The **Home** gear is Gearbox's box-agnostic app dashboard — a self-hosted
+start page with launcher tiles, service widgets, sparkline graphs,
+bookmarks, and a search bar. It's the first gear with
+`Info.Scope == ScopeSystem`: there is one row per install, not one per
+monitored box, since a dashboard isn't tied to a particular server.
+
+> **Implementation reference:** the canonical, code-adjacent docs live
+> alongside the source at
+> [`internal/gears/home/README.md`](../internal/gears/home/README.md) —
+> capabilities, routes, permissions, schema, and architecture notes.
+> This page is the **operator-facing overview** with quickstart and
+> common questions.
+
+## Quick start
+
+1. Sign in to Gearbox as an admin and enable the **Home** gear from
+   `Settings → Gears`. (Home is system-scoped, so it's listed in the
+   global gears section, not under any individual box.)
+2. Navigate to `/home/`. You'll see an empty board with an **+ Add tile**
+   button in the top-right.
+3. Click **+ Add tile**, paste an app's URL (e.g. `https://sonarr.example.com`),
+   tab out of the field. The backend probes well-known endpoints in
+   parallel; on a fingerprint hit, a green "Detected: <App>" banner
+   pre-fills name + icon + slug.
+4. For widget data, paste the upstream's API key into the **API Key**
+   field. Click **API Instructions** in the detection banner if you
+   need step-by-step guidance — works for Sonarr/Radarr/Prowlarr/
+   Lidarr/Readarr/Bazarr, qBittorrent, Plex, Jellyfin, Tautulli,
+   Pi-hole, AdGuard, Portainer, Immich, and UniFi.
+5. **Save**. The tile lands on the board and starts its 30-second
+   refresh loop.
+
+## Built-in widget providers
+
+Apps with first-class widgets (live data pills, server-rendered field
+maps over SSE):
+
+| App                  | Auth        | Sample fields                                          |
+|----------------------|-------------|--------------------------------------------------------|
+| Sonarr / Radarr      | API key     | `wanted`, `missing`, `queued`, `series` / `movies`     |
+| Lidarr / Readarr     | API key     | `wanted`, `queued`, `artists` / `books`                |
+| Prowlarr             | API key     | `numIndexers`, `numGrabs`, `numQueries`, `numFailQueries` |
+| qBittorrent          | basic auth  | `download`, `upload`, `leech`, `seed`                  |
+| Pi-hole              | API key     | `queries`, `blocked`, `blocked_percent`, `gravity`     |
+| Plex                 | `X-Plex-Token` | `streams`, `transcodes`, `bandwidth`, `movies`, `tv`, `episodes`, `libraries` |
+| UniFi Network        | `X-API-KEY` (Integration API) | `clients`, `wifi`, `wired`, `vpn`, `devices_online`, `devices_offline`, `wan_status`, `wan_down` *(graph)*, `wan_up` *(graph)*, `gateway_cpu`, `gateway_mem`, `uptime` |
+
+Apps in the catalog without a tier-1 provider still get launcher tiles
+(icon + name + reachability status). Adding a new provider is a
+small Go file; see the **Adding a Tier-1 widget provider** section in
+the gear's [internal README](../internal/gears/home/README.md).
+
+## Sparkline graphs
+
+Fields tagged `graphable: true` in the catalog (currently UniFi
+`wan_down` and `wan_up`) render an inline ~38×12 SVG trend line next
+to the value. The browser buffers the last 60 samples per
+tile×field in memory and scales each line to its buffer's min/max.
+Bandwidth values are normalized to bits/s before graphing so the
+trend stays smooth across Kbps↔Mbps unit boundaries.
+
+The buffer is **per session** — sparklines start from when you opened
+the dashboard and grow as updates arrive. UniFi's Integration API
+doesn't ship historical time-series, so anything older than the
+current session isn't available. After ~2 minutes of dashboard
+uptime you have 4 samples (1 every 30 s); after 30 minutes the buffer
+is at its 60-sample cap and starts rolling.
+
+## Security model (where do my API keys live?)
+
+API keys, basic-auth passwords, and bearer tokens are:
+
+- **Encrypted at rest** with the install's master key via the existing
+  AES-256-GCM `crypto.Encryptor` (the same primitive used for agent
+  API keys). Keys are stored in the `home_tile_secrets` table,
+  separate from `home_tiles` so the secret can be `JOIN`ed only by
+  code paths that need it.
+- **Used only by backend handlers**. All third-party API calls
+  (Sonarr, Plex, UniFi, etc.) are made by the Gearbox Go process
+  with the decrypted key in headers. The browser never has the key.
+- **Never serialized into responses or templ renders**. The widget
+  refresh sends the *rendered field map* (`{"streams": "2",
+  "bandwidth": "12.4 Mbps"}`) over SSE — the upstream's raw response
+  body never reaches the browser.
+- **Surfaced to the UI as `has_secret: true` only**. To see a stored
+  key after creation, you re-enter it (Stripe-style); there is no
+  "show key" button.
+
+If you compromise the Gearbox host, you can read the in-memory cache
+and decrypt at-rest secrets with the master key — that's the same
+threat model as every other secret in the app.
+
+## Configuration
+
+System-wide settings live on the gear's own `gears.config` JSON row
+(`server_id = '__system__'`, `name = 'home'`):
+
+```json
+{
+  "system_default_landing_path": "/home",
+  "health_checks_enabled": true,
+  "default_status_interval_seconds": 30,
+  "attribution_shown": false
+}
+```
+
+Per-tile cadence overrides live on the tile's own config JSON
+(`AppConfig.status_interval_seconds`, `AppConfig.status_checks_disabled`).
+
+## Backup / restore
+
+The gear ships with schema-versioned import/export at
+`/home/api/export` and `/home/api/import`. The JSON file is portable
+across installs, but **encrypted secrets are deliberately excluded**
+— carrying them across hosts would require sharing the master key,
+and we'd rather you re-enter keys on the destination than punch a
+hole in the threat model.

gearbox/go.mod

@@ -3,7 +3,7 @@ module github.com/sarg3nt/gearbox
 go 1.25.5
 
 require (
-	github.com/a-h/templ v0.3.977
+	github.com/a-h/templ v0.3.1001
 	github.com/go-chi/chi/v5 v5.2.4
 	github.com/go-webauthn/webauthn v0.15.0
 	github.com/golang-migrate/migrate/v4 v4.19.1

gearbox/go.sum

@@ -1,5 +1,7 @@
 github.com/a-h/templ v0.3.977 h1:kiKAPXTZE2Iaf8JbtM21r54A8bCNsncrfnokZZSrSDg=
 github.com/a-h/templ v0.3.977/go.mod h1:oCZcnKRf5jjsGpf2yELzQfodLphd2mwecwG4Crk5HBo=
+github.com/a-h/templ v0.3.1001 h1:yHDTgexACdJttyiyamcTHXr2QkIeVF1MukLy44EAhMY=
+github.com/a-h/templ v0.3.1001/go.mod h1:oCZcnKRf5jjsGpf2yELzQfodLphd2mwecwG4Crk5HBo=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/fxamacker/cbor/v2 v2.9.0 h1:NpKPmjDBgUfBms6tr6JZkTHtfFGcMKsw3eGcmD/sapM=

gearbox/internal/framework/database/database.go

@@ -90,6 +90,11 @@ func New(dbPath string, logger *slog.Logger) (*DB, error) {
 		return nil, fmt.Errorf("failed to initialize config schema: %w", err)
 	}
 
+	// Initialize Home dashboard schema (boards, tiles, secrets)
+	if err := d.initHomeSchema(); err != nil {
+		return nil, fmt.Errorf("failed to initialize home schema: %w", err)
+	}
+
 	// Run schema migrations AFTER all schemas are initialized
 	// (migrations may reference tables from any schema)
 	if err := d.runSchemaMigrations(); err != nil {