fix(onboarding): welcome-flow polish from manual testing

- Sidebar shows Home when it's the only enabled gear. The status
  middleware was short-circuiting on box-count==0 and never injecting
  system gears into the nav order; now system gears load first
  regardless of box state, and box-scoped gears are appended only
  when a box exists.
- /settings/gears no longer 400s with plain "No servers configured"
  when no boxes are registered. Renders the Home gear plus a "No
  boxes configured" CTA card linking to /settings/boxes/new. Inline
  copy switched to "box" terminology to match issue #49.
- Welcome screen uses the shared ui.Toggle slider instead of a bare
  <input type="checkbox">. ui.Toggle gained a value parameter so it
  can submit a specific value when multiple toggles share a name
  (multi-select checkbox group). CLAUDE.md adds "Toggle switches —
  never use a bare <input type=checkbox>" under UI Conventions so
  this stays the canonical pattern.
- Home empty-state icon scaled up via new HomeIconClass(class)
  wrapper. Sidebar HomeIcon() unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sarg3nt

CLAUDE.md

@@ -200,6 +200,28 @@ await showAlertDialog({
 
 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).
 
+### Toggle switches — never use a bare `<input type="checkbox">` in templates
+
+For every boolean input in a `.templ` file — feature opt-ins, settings, "enable this gear", "show all", per-row enable/disable — use the shared slider component in [internal/framework/ui/toggle.templ](gearbox/internal/framework/ui/toggle.templ):
+
+```templ
+import "github.com/sarg3nt/gearbox/internal/framework/ui"
+
+// Single toggle (no inline label — pair with your own <label for=...>)
+@ui.Toggle("welcome-gear-home", "gears", "home", false, false)
+// args: id, name, value (submitted when checked), checked, disabled
+
+// Toggle + label + description, stacked horizontally
+@ui.ToggleWithLabel("notify-email", "notify_email", "1", "Email notifications", "Send a digest each morning", true, false)
+```
+
+**Rules of thumb:**
+
+- The underlying input is `sr-only` but real — it submits with the form and respects `checked` / `disabled`. No JS required for plain forms.
+- Pass `value` when multiple toggles share a `name` (e.g., a multi-select checkbox group posting as `name="gears"`). Leave empty when a single boolean field submits as the default `"on"`.
+- For AJAX toggles that POST on change (no enclosing form), the per-row `gear-toggle` `<button role="switch">` pattern in [gears.templ](gearbox/internal/framework/templates/pages/gears.templ) is the established alternative — but for **anything inside a `<form>`**, use `@ui.Toggle`.
+- Never inline `peer-checked:after:...` Tailwind salads in a new template — that's a sign you should be calling `@ui.Toggle`. Existing inline copies in `overview.templ` and `admin_user_permissions.templ` are tech debt; migrate them when you're already editing those files.
+
 ## Key Constraints
 
 ### NEVER

gearbox/internal/framework/handler/gears.go

@@ -38,21 +38,23 @@ func (h *Handler) GearsPage(w http.ResponseWriter, r *http.Request) {
 		boxID = servers[0].ID
 	}
 
-	if boxID == "" {
-		http.Error(w, "No servers configured", http.StatusBadRequest)
-		return
-	}
-
-	// Ensure default gears exist for this server
-	if err := h.db.EnsureServerGears(boxID); err != nil {
-		h.logger.Error("Failed to ensure server gears", "error", err)
-	}
+	// boxID may be empty on a fresh install — the template renders an
+	// "Add a Box" CTA in place of the per-box gear list. System-scoped
+	// gears still render regardless.
+
+	var plugins []database.Gear
+	if boxID != "" {
+		// Ensure default gears exist for this box
+		if err := h.db.EnsureServerGears(boxID); err != nil {
+			h.logger.Error("Failed to ensure server gears", "error", err)
+		}
 
-	plugins, err := h.db.GetGears(boxID)
-	if err != nil {
-		h.logger.Error("Failed to get gears", "error", err)
-		http.Error(w, "Internal server error", http.StatusInternalServerError)
-		return
+		plugins, err = h.db.GetGears(boxID)
+		if err != nil {
+			h.logger.Error("Failed to get gears", "error", err)
+			http.Error(w, "Internal server error", http.StatusInternalServerError)
+			return
+		}
 	}
 
 	// Load system-scoped (box-agnostic) gears so they render alongside the

gearbox/internal/framework/handler/handler.go

@@ -186,6 +186,11 @@ func (h *Handler) getDefaultServerID() string {
 
 // InjectIntegrationStatus is middleware that adds integration status and user permissions to the request context.
 // This enables server-side conditional rendering of navigation items based on integration status and permissions.
+//
+// System-scoped gears (Home, etc. — keyed by database.SystemServerID) are
+// always loaded, even when no boxes are registered. Box-scoped gears load
+// from the default box if one exists; otherwise they're explicitly disabled
+// so the sidebar stays clean during first-run.
 func (h *Handler) InjectIntegrationStatus(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		ctx := r.Context()
@@ -196,69 +201,51 @@ func (h *Handler) InjectIntegrationStatus(next http.Handler) http.Handler {
 			ctx = auth.SetUserPermissions(ctx, perms)
 		}
 
-		boxID := h.getDefaultServerID()
-		if boxID != "" {
-			// Get integrations with their enabled status and sort order
+		status := make(map[string]bool)
+		orderedIntegrations := make([]auth.SidebarIntegration, 0)
+
+		// System gears go first so they render at the head of the nav.
+		systemGears, err := h.db.GetGears(database.SystemServerID)
+		if err != nil {
+			h.logger.Warn("failed to load system gears for sidebar", "error", err)
+		}
+		for _, sg := range systemGears {
+			status[sg.Name] = sg.Enabled
+			orderedIntegrations = append(orderedIntegrations, auth.SidebarIntegration{
+				Name:      sg.Name,
+				Enabled:   sg.Enabled,
+				SortOrder: sg.SortOrder,
+			})
+		}
+
+		if boxID := h.getDefaultServerID(); boxID != "" {
 			integrations, err := h.db.GetGears(boxID)
 			if err != nil {
 				h.logger.Error("failed to get integrations for sidebar", "error", err)
-				// Continue without status - sidebar will show all items (fail open)
-				next.ServeHTTP(w, r.WithContext(ctx))
-				return
-			}
-
-			// Merge in system-wide (box-agnostic) gears so the sidebar can show them.
-			systemGears, err := h.db.GetGears(database.SystemServerID)
-			if err != nil {
-				h.logger.Warn("failed to load system gears for sidebar", "error", err)
+			} else {
+				for _, i := range integrations {
+					status[i.Name] = i.Enabled
+					orderedIntegrations = append(orderedIntegrations, auth.SidebarIntegration{
+						Name:      i.Name,
+						Enabled:   i.Enabled,
+						SortOrder: i.SortOrder,
+					})
+				}
 			}
-
-			// Build status map for backward compatibility
-			status := make(map[string]bool)
-			for _, i := range integrations {
-				status[i.Name] = i.Enabled
-			}
-			for _, i := range systemGears {
-				status[i.Name] = i.Enabled
-			}
-
-			// Build ordered list for sidebar (box gears first, then system gears
-			// at the head — Home should sit at the top of navigation when enabled).
-			orderedIntegrations := make([]auth.SidebarIntegration, 0, len(integrations)+len(systemGears))
-			for _, i := range systemGears {
-				orderedIntegrations = append(orderedIntegrations, auth.SidebarIntegration{
-					Name:      i.Name,
-					Enabled:   i.Enabled,
-					SortOrder: i.SortOrder,
-				})
+		} else {
+			// No box configured — explicitly mark box-scoped gears off so
+			// the sidebar doesn't fall back to fail-open and clutter
+			// first-run with disabled items. System gears (Home) are
+			// already injected above and remain visible if enabled.
+			for _, n := range []string{"haproxy", "metrics", "logs", "services", "certificates", "traffic", "alerts", "os_updates"} {
+				if _, present := status[n]; !present {
+					status[n] = false
+				}
 			}
-			for _, i := range integrations {
-				orderedIntegrations = append(orderedIntegrations, auth.SidebarIntegration{
-					Name:      i.Name,
-					Enabled:   i.Enabled,
-					SortOrder: i.SortOrder,
-				})
-			}
-
-			ctx = auth.SetGearStatus(ctx, status)
-			ctx = auth.SetIntegrationOrder(ctx, orderedIntegrations)
-			next.ServeHTTP(w, r.WithContext(ctx))
-			return
 		}
 
-		// No server configured - explicitly disable all gears in navigation
-		// This provides a clean initial setup experience without gear clutter
-		status := map[string]bool{
-			"metrics":      false,
-			"logs":         false,
-			"services":     false,
-			"certificates": false,
-			"traffic":      false,
-			"alerts":       false,
-			"os_updates":   false,
-		}
 		ctx = auth.SetGearStatus(ctx, status)
-		ctx = auth.SetIntegrationOrder(ctx, []auth.SidebarIntegration{})
+		ctx = auth.SetIntegrationOrder(ctx, orderedIntegrations)
 		next.ServeHTTP(w, r.WithContext(ctx))
 	})
 }

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

@@ -74,28 +74,57 @@ templ GearsPage(user *models.User, servers []models.BoxConfig, currentServerID s
 				<div class="mb-6">
 					<div class="flex items-baseline justify-between mb-2">
 						<h3 class="text-base font-semibold text-gray-700 dark:text-gray-200">System</h3>
-						<span class="text-xs text-gray-500 dark:text-gray-400">Applies install-wide, not tied to a server</span>
+						<span class="text-xs text-gray-500 dark:text-gray-400">Applies install-wide, not tied to a box</span>
 					</div>
 					<div id="system-gears-list" class="space-y-4">
 						for _, sg := range systemGears {
 							@gearCard(sg, sg.ServerID)
 						}
 					</div>
 				</div>
-				<div class="mb-2">
-					<h3 class="text-base font-semibold text-gray-700 dark:text-gray-200">
-						if currentServerID != "" && len(servers) > 0 {
-							{ serverNameByID(servers, currentServerID) }
-						} else {
-							Server gears
-						}
-					</h3>
-				</div>
 			}
 
+			<div class="mb-2">
+				<h3 class="text-base font-semibold text-gray-700 dark:text-gray-200">
+					if currentServerID != "" && len(servers) > 0 {
+						{ serverNameByID(servers, currentServerID) }
+					} else {
+						Box gears
+					}
+				</h3>
+			</div>
 			<div id="gears-list" class="space-y-4">
-				for _, integration := range integrations {
-					@gearCard(integration, currentServerID)
+				if len(servers) > 0 {
+					for _, integration := range integrations {
+						@gearCard(integration, currentServerID)
+					}
+				} else {
+					<div class="bg-white dark:bg-slate-800 rounded-lg shadow p-6">
+						<div class="flex items-start gap-4">
+							<div class="flex-shrink-0 w-12 h-12 rounded-lg bg-blue-50 dark:bg-blue-900/30 flex items-center justify-center">
+								<svg class="w-6 h-6 text-blue-600 dark:text-blue-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+									<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 12h14M5 12a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v4a2 2 0 01-2 2M5 12a2 2 0 00-2 2v4a2 2 0 002 2h14a2 2 0 002-2v-4a2 2 0 00-2-2m-2-4h.01M17 16h.01"></path>
+								</svg>
+							</div>
+							<div class="flex-1 min-w-0">
+								<h4 class="text-base font-semibold text-gray-800 dark:text-gray-100">No boxes configured</h4>
+								<p class="mt-1 text-sm text-gray-600 dark:text-gray-400">
+									Per-box gears (HAProxy, Metrics, Logs, Services, Certificates, Traffic, Alerts, OS Updates) need a registered box to run against. Add one to enable them.
+								</p>
+								<div class="mt-4">
+									<a
+										href="/settings/boxes/new"
+										class="inline-flex items-center px-4 py-2 border border-transparent text-sm font-medium rounded-md shadow-sm text-white bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500"
+									>
+										<svg class="w-4 h-4 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+											<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4"></path>
+										</svg>
+										Add a Box
+									</a>
+								</div>
+							</div>
+						</div>
+					</div>
 				}
 			</div>
 

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

@@ -4,6 +4,7 @@ import (
 	"github.com/sarg3nt/gearbox/internal/framework/database"
 	"github.com/sarg3nt/gearbox/internal/framework/middleware"
 	"github.com/sarg3nt/gearbox/internal/framework/models"
+	"github.com/sarg3nt/gearbox/internal/framework/ui"
 )
 
 // WelcomePage is the first-run landing screen shown to an admin when nothing
@@ -99,18 +100,15 @@ templ WelcomePage(user *models.User, systemGears []database.Gear, csrfToken stri
 
 								<div class="space-y-3">
 									for _, g := range systemGears {
-										<label class="flex items-start p-4 rounded-md border border-gray-200 dark:border-gray-700 hover:bg-gray-50 dark:hover:bg-slate-700/50 cursor-pointer">
-											<input
-												type="checkbox"
-												name="gears"
-												value={ g.Name }
-												class="mt-1 h-4 w-4 text-blue-600 border-gray-300 rounded focus:ring-blue-500 dark:border-gray-600 dark:bg-slate-700"
-											/>
-											<span class="ml-3">
+										<div class="flex items-start p-4 rounded-md border border-gray-200 dark:border-gray-700 hover:bg-gray-50 dark:hover:bg-slate-700/50">
+											<div class="flex items-center h-5 mt-0.5 flex-shrink-0">
+												@ui.Toggle("welcome-gear-"+g.Name, "gears", g.Name, false, false)
+											</div>
+											<label for={ "welcome-gear-" + g.Name } class="ml-3 cursor-pointer flex-1">
 												<span class="block text-sm font-medium text-gray-900 dark:text-white">{ g.DisplayName }</span>
 												<span class="block text-sm text-gray-500 dark:text-gray-400">{ g.Description }</span>
-											</span>
-										</label>
+											</label>
+										</div>
 									}
 								</div>
 

gearbox/internal/framework/ui/toggle.templ

@@ -1,16 +1,23 @@
 package ui
 
-// Toggle creates a switch/toggle input component
+// Toggle creates a switch/toggle input component.
+//
 // id: unique identifier for the input
 // name: form field name
+// value: form value submitted when checked (empty string → defaults to "on")
 // checked: initial state
 // disabled: whether the toggle is disabled
-templ Toggle(id string, name string, checked bool, disabled bool) {
+//
+// This is the canonical toggle for the app. Always use it for boolean form
+// inputs in templates instead of a bare <input type="checkbox">. See
+// CLAUDE.md → UI Conventions → Toggle switches.
+templ Toggle(id string, name string, value string, checked bool, disabled bool) {
 	<label class={ "relative inline-flex items-center", templ.KV("cursor-pointer", !disabled), templ.KV("cursor-not-allowed opacity-50", disabled) }>
 		<input
 			type="checkbox"
 			id={ id }
 			name={ name }
+			value={ value }
 			class="sr-only peer"
 			checked?={ checked }
 			disabled?={ disabled }
@@ -20,10 +27,10 @@ templ Toggle(id string, name string, checked bool, disabled bool) {
 }
 
 // ToggleWithLabel creates a toggle with an accompanying label
-templ ToggleWithLabel(id string, name string, label string, description string, checked bool, disabled bool) {
+templ ToggleWithLabel(id string, name string, value string, label string, description string, checked bool, disabled bool) {
 	<div class="flex items-start">
 		<div class="flex items-center h-5">
-			@Toggle(id, name, checked, disabled)
+			@Toggle(id, name, value, checked, disabled)
 		</div>
 		<div class="ml-3">
 			<label for={ id } class={ "text-sm font-medium text-gray-900 dark:text-gray-100", templ.KV("cursor-pointer", !disabled), templ.KV("cursor-not-allowed", disabled) }>

gearbox/internal/gears/home/icons.go

@@ -2,23 +2,33 @@ package home
 
 import (
 	"context"
+	"fmt"
 	"io"
 
 	"github.com/a-h/templ"
 )
 
-// HomeIcon returns the SVG icon component for the Home gear sidebar entry.
-//
-// Path is the canonical Heroicons v1 "home" outline: a roof with both
+// homeIconPath is the canonical Heroicons v1 "home" outline: a roof with both
 // walls reaching it, a small door cut in the bottom-center. The previous
-// path was a malformed variant whose right wall stopped halfway up,
-// leaving a visual gap (issue: "the right wall is missing"). It also
-// drew a stray vertical stroke down the middle.
+// path was a malformed variant whose right wall stopped halfway up, leaving
+// a visual gap (issue: "the right wall is missing"). It also drew a stray
+// vertical stroke down the middle.
+const homeIconPath = `M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6`
+
+// HomeIcon returns the home SVG sized for the sidebar entry (w-5 h-5).
+// For other sizes use HomeIconClass.
 func HomeIcon() templ.Component {
+	return HomeIconClass("w-5 h-5")
+}
+
+// HomeIconClass returns the home SVG with caller-supplied Tailwind classes
+// (e.g. "w-16 h-16") so the same icon can be reused at larger sizes
+// without duplicating the SVG markup.
+func HomeIconClass(class string) templ.Component {
 	return templ.ComponentFunc(func(ctx context.Context, w io.Writer) error {
-		_, err := io.WriteString(w, `<svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
-			<path stroke-linecap="round" stroke-linejoin="round" d="M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6"></path>
-		</svg>`)
+		_, err := fmt.Fprintf(w, `<svg class=%q fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">`+
+			`<path stroke-linecap="round" stroke-linejoin="round" d=%q></path>`+
+			`</svg>`, class, homeIconPath)
 		return err
 	})
 }

gearbox/internal/gears/home/pages.templ

@@ -249,8 +249,8 @@ templ IndexPage(d IndexPageData) {
 		<div class="px-4 sm:px-6 lg:px-8 py-6">
 			if len(d.Tiles) == 0 {
 				<div id="home-empty-state" class="border-2 border-dashed border-gray-300 dark:border-slate-700 rounded-xl py-16 text-center">
-					<div class="mx-auto h-12 w-12 text-gray-400 dark:text-gray-500 mb-3">
-						@HomeIcon()
+					<div class="mx-auto text-gray-400 dark:text-gray-500 mb-4 flex justify-center">
+						@HomeIconClass("w-20 h-20")
 					</div>
 					<h2 class="text-lg font-semibold text-gray-700 dark:text-gray-200">Your dashboard is empty</h2>
 					<p class="mt-2 text-sm text-gray-500 dark:text-gray-400 max-w-md mx-auto">