Merge remote-tracking branch 'origin/main' into feature/45-held-packages

# Conflicts:
#	gearbox-agent/internal/gears/updates/updates_test.go

Author: sarg3nt

CLAUDE.md

@@ -102,26 +102,9 @@ When a new feature is planned or a bug is reported:
 7. **Track Progress** — Keep the project board and issues in sync
 8. **Complete** — When user confirms done: merge PR, close issue, move project card to Done
 
-### Branch Naming Convention
+### Branching, PR, and label conventions
 
-- **Features:** `feature/short-description` (e.g., `feature/dashboard-export`)
-- **Bug fixes:** `fix/short-description` (e.g., `fix/websocket-reconnect`)
-- **Always branch from `main`**
-
-### PR Convention
-
-- All PRs target `main`
-- PR body must include `Closes #<issue-number>` to auto-close the issue on merge
-- Use the standard PR template format (Summary, Test Plan)
-
-### Issue Labels
-
-Use these labels consistently:
-
-- `enhancement` — New features
-- `bug` — Bug fixes
-- `documentation` — Docs-only changes
-- `refactor` — Code improvements without behavior change
+Generic branching/PR/label rules live in `~/.claude/CLAUDE.md`. All of them apply here unmodified — `feature/...` and `fix/...` branches from `main`, `Closes #N` in PR bodies, the four standard labels.
 
 ### Project Board
 
@@ -151,14 +134,6 @@ TASKS.md is a **scratch pad only** — not a tracking system. The GitHub Project
 - `/dowork` - Read TASKS.md, create issues from it, and start working (ask questions as needed)
 - `/doallwork` - Read TASKS.md, create issues from it, and work autonomously
 
-## User Preferences
-
-### Code Block Formatting
-
-- **Always use fenced code blocks** (triple backticks) for commands
-- 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()`
@@ -200,6 +175,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
@@ -219,13 +216,9 @@ Existing reference usages: [user-pages/admin-user-detail.js](static/js/user-page
 - Inform user before running `make deploy` for agent
 - Validate HAProxy config with `haproxy -c` before reload (if applicable)
 
-### Markdown Linting
-
-Run `npx markdownlint-cli '**/*.md' --config .markdownlint.json` to validate. Key rules: blank lines around lists/code blocks, specify language for code blocks, proper headings, single newline at EOF.
-
-### Creating New Documentation
+### Markdown and docs
 
-Store in `docs/` directory using kebab-case naming. Include TOC after main heading. Reference in README.md.
+See `~/.claude/CLAUDE.md` for markdown style and the `docs/` + kebab-case rule. This repo also requires a TOC after the main heading in new docs.
 
 ### Creating Reports and Scan Results
 

DESIGN.md

@@ -71,17 +71,53 @@ Each gear is self-contained: it defines its own routes, handlers, templates, and
 
 Gears progress through a state machine: `disabled` → `alpha` → `beta` → `production`. Alpha and beta gears must be explicitly enabled by the user. Production gears are enabled by default. The `disabled` state excludes the gear from the build entirely.
 
-### Dashboard Gears (7)
-
-| Gear         | Purpose                                      |
-|--------------|----------------------------------------------|
-| HAProxy      | HAProxy overview, status grid, and backend/frontend/server monitoring |
-| Metrics      | Historical CPU, memory, disk, network charts |
-| Services     | Systemd service monitoring and control       |
-| Certificates | TLS certificate expiration tracking          |
-| Logs         | Real-time log viewing and search             |
-| Traffic      | Traffic analysis and GeoIP visualization     |
-| Alerts       | Alert rules, notifications, and history      |
+### Gear Scopes
+
+Each gear declares a `Scope` controlling where its rows live in the database
+and how the sidebar treats it (see [`internal/framework/gear/interface.go`](gearbox/internal/framework/gear/interface.go)):
+
+- **`ScopeBox`** *(default)* — one row per (box_id, gear_name) in the gears
+  table. The gear is shown in the sidebar only when an active box context
+  is set, because its UI is meaningless without one. Examples: HAProxy,
+  Metrics, Logs, Services, Certificates, Traffic, Alerts, OS Updates.
+- **`ScopeSystem`** — a single install-wide row keyed by the
+  `SystemServerID` sentinel. The gear is always visible in the sidebar and
+  ignores box context. Example: the Home dashboard.
+- **`ScopeBoxAgnostic`** — install-wide like `ScopeSystem` but
+  semantically the gear lists or aggregates *across* boxes rather than
+  ignoring them. Always visible; box-specific gears are hidden when no box
+  is active because this gear is the place to pick one. Example: the Bx
+  fleet view.
+
+### Multi-box UX
+
+A single Gearbox dashboard connects to many agents. The user picks which box
+they are "in" via two affordances backed by the same `?box_id=<id>` query
+convention:
+
+1. **Bx fleet view** at `/bx` — a `ScopeBoxAgnostic` gear that lists every
+   configured box with live status dots and click-through to that box.
+2. **Persistent box-switcher chip** in the chrome — opens a Cockpit-style
+   command palette (search + arrow-keys; `g b` shortcut) for jumping
+   between boxes mid-task without losing place.
+
+When no box is selected, box-scoped gears are hidden from the sidebar; the
+user sees only `Bx`, `Home`, and `Settings`. Selecting a box hydrates the
+sidebar with that box's enabled gears.
+
+### Dashboard Gears (8)
+
+| Gear         | Scope        | Purpose                                       |
+|--------------|--------------|-----------------------------------------------|
+| Bx           | box-agnostic | Fleet overview: list + status + switcher home |
+| Home         | system       | App dashboard with launcher tiles and widgets |
+| HAProxy      | box          | HAProxy overview, status grid, and backend/frontend/server monitoring |
+| Metrics      | box          | Historical CPU, memory, disk, network charts  |
+| Services     | box          | Systemd service monitoring and control        |
+| Certificates | box          | TLS certificate expiration tracking           |
+| Logs         | box          | Real-time log viewing and search              |
+| Traffic      | box          | Traffic analysis and GeoIP visualization      |
+| Alerts       | box          | Alert rules, notifications, and history       |
 
 ### Agent Gears (7)
 

gearbox-agent/deploy/gearbox-agent.service

@@ -17,10 +17,6 @@ Environment=HOME=/root
 Environment=HAPROXY_AGENT_LISTEN=0.0.0.0:8405
 Environment=HAPROXY_AGENT_DATA_DIR=/var/lib/gearbox-agent
 Environment=HAPROXY_AGENT_LOG_LEVEL=info
-# pipx derives its log dir from XDG_STATE_HOME ($XDG_STATE_HOME/pipx/log).
-# Redirect to /tmp so ProtectHome=read-only doesn't cause pipx to crash before
-# listing packages. PrivateTmp=true ensures cleanup on service stop.
-Environment=XDG_STATE_HOME=/tmp/xdg-state
 
 # Optional: Load additional environment from file
 EnvironmentFile=-/etc/default/gearbox-agent
@@ -34,8 +30,19 @@ RestartSec=5
 # access to /etc (HAProxy config, certificates) and /var (package management,
 # data dir). ProtectHome=read-only is set since the agent runs as root and only
 # needs read access to home directories.
+#
+# pipx upgrades write new package files into /root/.local/share/pipx/venvs/<pkg>/,
+# pipx logs to /root/.local/state/pipx/log/, pipx CLI shims live at /root/.local/bin/,
+# and pip caches downloads under /root/.cache/pip/ — all inside the otherwise
+# read-only /root. We grant the broader XDG data/cache parents (/root/.local and
+# /root/.cache) rather than narrower per-tool subdirs because pipx and pip create
+# their state/log/cache subdirectories on demand at first use, and the mkdir of
+# e.g. /root/.local/state/pipx/ requires the /root/.local/state/ parent to be
+# writable. Nothing security-sensitive lives under either XDG dir on this host.
+# The "-" prefix tolerates the paths not existing yet.
 NoNewPrivileges=false
 ProtectHome=read-only
+ReadWritePaths=-/root/.local -/root/.cache
 PrivateTmp=true
 ProtectKernelTunables=true
 

gearbox-agent/internal/gears/updates/updates.go

@@ -222,11 +222,23 @@ func (c *UpdatesCollector) runPipxCommand(args ...string) ([]byte, error) {
 }
 
 // runPipxCommandWithOutput runs a pipx command and wraps failures with the
-// command's output, just like runCommandWithOutput does for regular commands.
+// command's output. Pipx's failure messages don't follow apt's "E:" convention,
+// so we use a pipx-tuned extractor that surfaces multiple trailing lines rather
+// than just the final "<long-path>/python -m pip install --upgrade pkg -q' failed"
+// summary line — that line on its own is missing the actual pip diagnostic.
+//
+// On failure the full output is also logged via slog at Warn level so operators
+// can dig into the agent log for full pip stdout/stderr; the returned error is
+// shorter and dashboard-friendly.
 func (c *UpdatesCollector) runPipxCommandWithOutput(args ...string) ([]byte, error) {
 	output, err := c.runPipxCommand(args...)
 	if err != nil {
-		errDetail := extractErrorLines(output)
+		slog.Warn("pipx command failed",
+			"args", args,
+			"err", err,
+			"output", strings.TrimSpace(string(output)),
+		)
+		errDetail := extractPipxErrorDetail(output)
 		if errDetail != "" {
 			return output, errors.New(errDetail)
 		}
@@ -235,6 +247,50 @@ func (c *UpdatesCollector) runPipxCommandWithOutput(args ...string) ([]byte, err
 	return output, nil
 }
 
+// extractPipxErrorDetail collects the most useful diagnostic lines from pipx
+// output for surfacing in a wrapped error. Unlike apt, pipx's failure summary
+// is typically the final line ("'<python> -m pip install --upgrade pkg -q' failed")
+// while the cause (network error, dependency conflict, missing module, etc.)
+// is on lines above it. We therefore return up to the last few non-empty lines
+// joined with "; ", capped at a reasonable display length.
+//
+// No prefix-based filtering: pip diagnostics legitimately use "Failed to …"
+// prefixes too (e.g. "Failed to build wheels for cryptography"), and those
+// are exactly the actionable lines we want to surface.
+func extractPipxErrorDetail(output []byte) string {
+	if len(output) == 0 {
+		return ""
+	}
+
+	text := strings.TrimSpace(string(output))
+	if text == "" {
+		return ""
+	}
+
+	const maxLines = 5
+	const maxTotalLen = 500
+
+	rawLines := strings.Split(text, "\n")
+	var picked []string
+	for i := len(rawLines) - 1; i >= 0 && len(picked) < maxLines; i-- {
+		trimmed := strings.TrimSpace(rawLines[i])
+		if trimmed == "" {
+			continue
+		}
+		picked = append([]string{trimmed}, picked...)
+	}
+
+	if len(picked) == 0 {
+		return ""
+	}
+
+	joined := strings.Join(picked, "; ")
+	if len(joined) > maxTotalLen {
+		joined = joined[:maxTotalLen] + "..."
+	}
+	return joined
+}
+
 // CheckUpdates retrieves the current update status.
 func (c *UpdatesCollector) CheckUpdates() (*UpdateInfo, error) {
 	return c.PM().CheckUpdates()

gearbox-agent/internal/gears/updates/updates_test.go

@@ -526,3 +526,82 @@ func TestApplyHeldMarks(t *testing.T) {
 		}
 	})
 }
+
+// TestExtractPipxErrorDetail verifies that pipx error extraction surfaces the
+// last few meaningful lines of pipx output rather than just the final
+// "'...python -m pip install --upgrade pkg -q' failed" summary — which on its
+// own loses the diagnostic that explains *why* the upgrade failed.
+func TestExtractPipxErrorDetail(t *testing.T) {
+	tests := []struct {
+		name     string
+		output   string
+		wantSubs []string // every substring must appear in the result
+		notWant  []string // none of these may appear
+		empty    bool     // expect empty string
+	}{
+		{
+			name:   "empty input",
+			output: "",
+			empty:  true,
+		},
+		{
+			name:   "whitespace only",
+			output: "   \n\t\n  \n",
+			empty:  true,
+		},
+		{
+			name: "real-world pipx failure surfaces cause and summary",
+			output: "Upgrading certbot...\n" +
+				"ERROR: Could not find a version that satisfies the requirement certbot==9.99\n" +
+				"ERROR: No matching distribution found for certbot==9.99\n" +
+				"'/root/.local/share/pipx/venvs/certbot/bin/python -m pip install --upgrade certbot -q' failed",
+			wantSubs: []string{
+				"No matching distribution found",
+				"--upgrade certbot -q' failed",
+			},
+		},
+		{
+			name: "surfaces Failed to lines from pip (e.g. build-wheel failures)",
+			output: "Collecting cryptography\n" +
+				"Failed to build wheels for cryptography\n" +
+				"'/root/.local/share/pipx/venvs/foo/bin/python -m pip install --upgrade foo -q' failed",
+			wantSubs: []string{
+				"Failed to build wheels for cryptography",
+				"--upgrade foo -q' failed",
+			},
+		},
+		{
+			name:   "caps at 5 lines",
+			output: "l1\nl2\nl3\nl4\nl5\nl6\nl7",
+			wantSubs: []string{"l3", "l4", "l5", "l6", "l7"},
+			notWant:  []string{"l1", "l2"},
+		},
+		{
+			name:   "truncates very long combined output",
+			output: strings.Repeat("a", 600),
+			wantSubs: []string{"..."},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := extractPipxErrorDetail([]byte(tc.output))
+			if tc.empty {
+				if got != "" {
+					t.Errorf("expected empty, got %q", got)
+				}
+				return
+			}
+			for _, sub := range tc.wantSubs {
+				if !strings.Contains(got, sub) {
+					t.Errorf("missing substring %q in result %q", sub, got)
+				}
+			}
+			for _, sub := range tc.notWant {
+				if strings.Contains(got, sub) {
+					t.Errorf("unexpected substring %q in result %q", sub, got)
+				}
+			}
+		})
+	}
+}