From 20b3a22c8832a2ddcc78b1cdd6b430d02f8eebed Mon Sep 17 00:00:00 2001
From: kisfenyo <nagyfenyvesi.viktor@gmail.com>
Date: Tue, 17 Feb 2026 20:46:50 +0100
Subject: [PATCH] Bug hunt and TASK.md for Sonnet

---
 TASK.md              |  710 ++++++++++++++++++++++------
 controller/README.md | 1045 +++++++++++++++++++++++++-----------------
 2 files changed, 1190 insertions(+), 565 deletions(-)

diff --git a/TASK.md b/TASK.md
index b0e8062..65483a4 100644
--- a/TASK.md
+++ b/TASK.md
@@ -1,192 +1,616 @@
-# 0.12.2 - Bug 4: Restore Section ("Visszaállítás") Simplification — TASK.md
+# TASK.md — Bug Fix Plan for Sonnet 4.5
 
-## Current State
+## Prompt / Context Gathering
 
-### Backup architecture (what goes where)
+Before starting any fixes, read the following files to understand the project:
 
-**Restic snapshots** (daily, on SSD):
-- `/opt/docker/stacks/` — all Docker configs, compose files, app.yaml
-- `/opt/docker/db-dumps/` — DB dump SQL files
-- `/opt/docker/felhom-controller/controller.yaml`
-- App HDD data paths (if backup enabled) — e.g., `/mnt/hdd_1/storage/immich/`
+1. **`controller/README.md`** — Full architecture, module map, API endpoints, feature documentation
+2. **`CHANGELOG.md`** — Recent changes (sessions 26-38, 2026-02-17) for context on what was implemented
+3. **`controller/TASK.md`** (this file) — The bug list and fix instructions
 
-**Cross-drive backups** (per-app, rsync/restic to secondary drive):
-- Copies app user data between drives (e.g., HDD→SSD or SSD→HDD)
-- Separate from restic — not part of snapshot restore
+Then read each source file listed in a bug section before fixing it.
 
-**Key detail:** `SnapshotInfo.Paths []string` from `restic snapshots --json` includes the backup source paths. Snapshots created BEFORE an app's HDD backup was enabled won't have that app's HDD paths listed. This can be used for filtering.
-
-### Current restore UI flow (backups.html Section 7)
-1. **App dropdown** — only apps with `HasHDDData && BackupEnabled` (filters out auto-only apps)
-2. **Snapshot dropdown** — loads ALL snapshots from `/api/backup/snapshots` (no filtering by app)
-3. **Path display** — shows HDD paths that will be restored (technical, confusing for customers)
-4. **Warning block** — "FELÜLÍRJA a jelenlegi adatait... NEM vonható vissza!... Javasoljuk az alkalmazás leállítását"
-5. **Confirmation checkbox** — "Megértettem, visszaállítás saját felelősségre"
-6. **Restore button** → POST `/backup/restore` with `stack_name` + `snapshot_id`
-
-### Current restore backend (`RestoreApp` in `restore.go`)
-- Validates backup enabled + snapshot exists
-- Resolves app's HDD paths via `GetStackHDDMounts()`
-- Runs `restic restore {snapshot} --target / --include {path1} --include {path2}`
-- Only restores HDD data — does NOT restore Docker configs or DB dumps
+**After all fixes are complete**, update:
+- `CHANGELOG.md` — Add a new entry at the top following the existing format (session 39, next version **v0.12.3**)
+- `controller/README.md` — If any fix changes behavior, API, or architecture, update the relevant section
 
 ---
 
-## Problems
+## Fix Priority
 
-1. **Snapshot selector shows ALL snapshots** — user can pick one that predates their app's backup setup → restore fails or does nothing
-2. **Path display is confusing** — customers don't need to see `/mnt/hdd_1/storage/immich/`
-3. **Warning is intimidating** — multiple strong statements, feels dangerous
-4. **No auto-stop** — just "recommended" to stop the app, user can forget
-5. **DB-only restore** is implicitly possible (pick old snapshot) but not clear what it does
+Fixes are organized into 3 tiers:
+
+- **CRITICAL** — Data races, security vulnerabilities, data loss risks. Fix these first.
+- **HIGH** — Logic errors, resource leaks, incorrect behavior. Fix these second.
+- **MEDIUM** — Edge cases, code quality, minor issues. Fix if time allows.
 
 ---
 
-## Proposed Design
+## CRITICAL Fixes
 
-### Simplified UI (3 elements instead of 6)
+### C1. Data race on `m.lastDBDump.Results` mutation (backup/backup.go)
 
-```
-┌─────────────────────────────────────────────────┐
-│  Visszaállítás                                   │
-│                                                   │
-│  Alkalmazás:  [▼ Immich                      ]   │
-│  Pillanatkép: [▼ 2026-02-17 03:00 (a3f2b1)  ]   │
-│                                                   │
-│  ⚠ A visszaállítás felülírja az alkalmazás      │
-│    jelenlegi adatait a kiválasztott mentés        │
-│    állapotával. Az alkalmazás a folyamat során    │
-│    automatikusan leáll és újraindul.             │
-│                                                   │
-│  ☐ Megértettem, visszaállítás indítása           │
-│                                                   │
-│  [ Visszaállítás indítása ]                      │
-└─────────────────────────────────────────────────┘
-```
+**File:** `internal/backup/backup.go`, around lines 556-570
 
-### Changes
+**Problem:** In `RefreshCache()`, the code mutates `m.lastDBDump.Results[i].Validation` while holding NO lock. The mutex is only acquired later at line 574. Other goroutines reading `m.lastDBDump` via `GetFullStatus()` can see torn writes.
 
-| # | What | Details |
-|---|------|---------|
-| 1 | **Filter snapshots by app** | When app selected, `/api/backup/snapshots?stack={name}` returns only snapshots whose `Paths` contain at least one of the app's HDD paths. Show snapshot time in human-friendly format, no raw IDs |
-| 2 | **Remove path display** | Customer doesn't need to see mount paths. The restore handler knows what to include |
-| 3 | **Single calm warning** | Replace 3-line warning + separate checkbox label with one concise block |
-| 4 | **Auto-stop + restart** | Restore handler stops the app's containers before restore, restarts after. Eliminates "javasoljuk leállítását" advice |
-| 5 | **Hide DB-only restore** | Not exposed in UI — support contacts Viktor for CLI-level `restic restore` |
+**Fix:** Move the `m.lastDBDump.Results` mutation block (lines 556-570) inside the `m.mu.Lock()` section that starts at line 574. The re-validation loop should happen after acquiring the lock, before setting `m.cachedStatus`.
 
 ---
 
-## Implementation Plan
+### C2. SnapshotHistory reversed after unlock (backup/backup.go)
 
-### Backend changes
+**File:** `internal/backup/backup.go`, around lines 582-589
 
-**1. Filtered snapshots API** (`internal/web/api_router.go` or `router.go`)
+**Problem:** `m.cachedStatus = status` is set at line 582 while holding the lock, but the snapshot history reversal at lines 587-589 happens AFTER `m.mu.Unlock()`. Since `status.SnapshotHistory` is a slice backed by the same array as `m.cachedStatus.SnapshotHistory` (created by `copy` which copies elements but shares nothing — wait, actually `copy` creates a new backing array, so this is safe for the array). However, the local `status` variable IS `m.cachedStatus` (assigned at line 582), so reversing `status.SnapshotHistory` also reverses `m.cachedStatus.SnapshotHistory` without the lock.
 
-Extend `GET /api/backup/snapshots` with optional `?stack={name}` query param:
+**Fix:** Move the reversal loop (lines 587-589) BEFORE `m.mu.Unlock()`, right after `copy(status.SnapshotHistory, m.snapshotHistory)` at line 581 and before assigning to `m.cachedStatus` at line 582.
+
+---
+
+### C3. `SetStackProvider` write without synchronization (backup/backup.go)
+
+**File:** `internal/backup/backup.go`, line 413-415
+
+**Problem:** `m.stackProvider = provider` is a direct field write with no mutex protection. The field is read by `resolveAppBackupPaths()` and `RefreshCache()` concurrently.
+
+**Fix:** Wrap the assignment in `m.mu.Lock()` / `m.mu.Unlock()`.
+
+---
+
+### C4. `GetFullStatus` shallow-copies mutable pointers (backup/backup.go)
+
+**File:** `internal/backup/backup.go`, lines 619-620
+
+**Problem:** `status.LastDBDump = m.lastDBDump` and `status.LastBackup = m.lastBackup` copy pointer values. Callers can mutate the referenced objects, creating races with the manager's internal state.
+
+**Fix:** Deep-copy these structs. If `lastDBDump` is non-nil, create a copy: `copyDump := *m.lastDBDump; status.LastDBDump = &copyDump`. Same for `lastBackup`. Also deep-copy the `Results` slice inside `lastDBDump` if present (since it's a slice of structs, a simple `copy` into a new slice suffices).
+
+---
+
+### C5. `IsSystemDisk` uses 8-bit major mask (storage/safety_linux.go)
+
+**File:** `internal/storage/safety_linux.go`, lines 30-31
+
+**Problem:** `major := (stat.Rdev >> 8) & 0xff` extracts only 8 bits. Linux dev_t uses a 12-bit major: bits 8-19 with bits 0-7 at positions 8-15 and bits 8-11 at positions 44-47 (for 64-bit). For the common case, the formula should use `unix.Major()` from `golang.org/x/sys/unix` or at minimum the standard extraction: `major = (dev & 0xfff00) >> 8`. Also, the function only compares major numbers — ALL SCSI disks share major 8, so this blocks formatting of any SCSI disk if root is also SCSI.
+
+**Fix:** Use `unix.Major(uint64(stat.Rdev))` and `unix.Minor(uint64(stat.Rdev))` from `golang.org/x/sys/unix` (already a dependency). Compare both major AND the disk portion of the minor to identify the physical disk. For SCSI (major 8), disks are distinguished by `minor / 16`. For NVMe (major 259), compare the whole-disk minor. The simplest correct approach: resolve both device paths to their parent disk name (e.g., via `partitionToParentDisk`) and compare those names instead of using device numbers.
+
+---
+
+### C6. No `/dev/` prefix validation on `DevicePath` (storage/format_linux.go)
+
+**File:** `internal/storage/format_linux.go`, around lines 37-41
+
+**Problem:** The `FormatAndMount` function accepts `DevicePath` from user JSON without validating it starts with `/dev/`. An attacker could pass arbitrary paths.
+
+**Fix:** At the start of `FormatAndMount`, validate:
 ```go
-func (r *Router) snapshotsHandler(w http.ResponseWriter, req *http.Request) {
-    snapshots, err := r.backupMgr.ListSnapshots(50)
-    // ... existing error handling ...
-    
-    // Filter by stack if requested
-    if stackName := req.URL.Query().Get("stack"); stackName != "" {
-        hddMounts := r.stackProvider.GetStackHDDMounts(stackName)
-        if len(hddMounts) > 0 {
-            snapshots = filterSnapshotsByPaths(snapshots, hddMounts)
-        }
-    }
-    
-    writeJSON(w, http.StatusOK, apiResponse{OK: true, Data: snapshots})
+if !strings.HasPrefix(req.DevicePath, "/dev/") {
+    return fmt.Errorf("invalid device path: must start with /dev/")
 }
+if strings.Contains(req.DevicePath, "..") {
+    return fmt.Errorf("invalid device path: must not contain ..")
+}
+```
 
-func filterSnapshotsByPaths(snapshots []backup.SnapshotInfo, requiredPaths []string) []backup.SnapshotInfo {
-    var filtered []backup.SnapshotInfo
-    for _, snap := range snapshots {
-        for _, req := range requiredPaths {
-            for _, sp := range snap.Paths {
-                if strings.HasPrefix(req, sp) || strings.HasPrefix(sp, req) {
-                    filtered = append(filtered, snap)
-                    goto next
-                }
+---
+
+### C7. Path traversal in `extractName` (api/router.go)
+
+**File:** `internal/api/router.go`, lines 769-771
+
+**Problem:** `extractName()` extracts a stack name from the URL path but doesn't reject `..`, `/`, or `\` characters. This name is used in file paths and Docker commands.
+
+**Fix:** Add validation after extracting the name:
+```go
+func extractName(r *http.Request) string {
+    name := // ... existing extraction logic
+    if strings.ContainsAny(name, "/\\") || name == ".." || name == "." || name == "" {
+        return ""
+    }
+    return name
+}
+```
+Then ensure all callers handle empty string as an error (most already check `name == ""`).
+
+---
+
+### C8. Path traversal in `TargetPath` (web/storage_handlers.go)
+
+**File:** `internal/web/storage_handlers.go`, around lines 374-417
+
+**Problem:** Migration API accepts `TargetPath` from user input without validating it's a registered storage path. Allows writing to arbitrary filesystem locations.
+
+**Fix:** Validate `TargetPath` against the list of registered storage paths from settings:
+```go
+registeredPaths := s.settings.GetStoragePaths() // or equivalent
+valid := false
+for _, p := range registeredPaths {
+    if req.TargetPath == p.Path {
+        valid = true
+        break
+    }
+}
+if !valid {
+    http.Error(w, "invalid target path", http.StatusBadRequest)
+    return
+}
+```
+
+---
+
+### C9. Path traversal in `DestinationPath` (api/router.go)
+
+**File:** `internal/api/router.go`, in `saveCrossDriveConfig()` around lines 587-644
+
+**Problem:** `DestinationPath` from user JSON not validated against registered storage paths. Allows cross-drive backup to write anywhere.
+
+**Fix:** Same pattern as C8 — validate `DestinationPath` against registered storage paths. Also validate it's not the same device as the source (this check may already exist in `crossdrive.go`, but the API should validate early).
+
+---
+
+### C10. Path traversal in `ParseComposeHDDMounts` (stacks/delete.go)
+
+**File:** `internal/stacks/delete.go`, lines 243-251
+
+**Problem:** After `${HDD_PATH}` substitution, the resulting path is checked with `strings.HasPrefix(hostPath, hddPath)` BEFORE `filepath.Clean`. An attacker could craft `${HDD_PATH}/../../etc/passwd` — the prefix check passes, but the resolved path escapes the HDD directory.
+
+**Fix:** Apply `filepath.Clean()` to the resolved path BEFORE the prefix check:
+```go
+resolved := filepath.Clean(hostPath)
+if !strings.HasPrefix(resolved, filepath.Clean(hddPath) + string(filepath.Separator)) {
+    continue // skip paths that escape HDD directory
+}
+```
+
+---
+
+## HIGH Fixes
+
+### H1. `ValidateDump` reads entire file into memory (backup/dbdump.go)
+
+**File:** `internal/backup/dbdump.go`, line 251
+
+**Problem:** `os.ReadFile(filePath)` loads entire SQL dump into memory. For large databases (500MB+), this causes massive memory allocation during every 5-minute cache refresh.
+
+**Fix:** Replace with `bufio.Scanner` reading line by line, or `io.LimitReader` to read only the first N bytes (e.g., 64KB for header) and last N bytes (for footer/completion markers). The validation only checks for structural markers like `CREATE TABLE`, `INSERT INTO`, completion tags — these are at the start and end of the file.
+
+---
+
+### H2. `du` calls without timeout (backup/appdata.go)
+
+**File:** `internal/backup/appdata.go`, lines 136 and 150
+
+**Problem:** `exec.Command("du", "-sh", path)` and `exec.Command("du", "-sb", path)` have no timeout. Can hang on slow/unmounted filesystems, blocking the web UI.
+
+**Fix:** Use `exec.CommandContext` with a 30-second timeout:
+```go
+ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+defer cancel()
+cmd := exec.CommandContext(ctx, "du", "-sh", path)
+```
+
+---
+
+### H3. Double `du` invocation per mount (backup/appdata.go)
+
+**File:** `internal/backup/appdata.go`, lines 79-80
+
+**Problem:** Both `appDirSizeBytes(mount)` and `appDirSizeHuman(mount)` run `du` independently. That's 2 subprocess calls per mount point.
+
+**Fix:** Create a single function `appDirSize(path string) (int64, string)` that runs `du -sb` once, parses the byte count, and formats the human string using `humanizeBytes()`. Replace both calls with this single function.
+
+---
+
+### H4. Snapshot validation only checks first 100 (backup/restore.go)
+
+**File:** `internal/backup/restore.go`, line 22
+
+**Problem:** `m.restic.ListSnapshots(100)` limits to 100 snapshots. Older snapshots can't be restored.
+
+**Fix:** Either:
+- Pass 0 or a very large number to list all snapshots, OR
+- Better: validate the snapshot ID format with a regex (`^[0-9a-f]{8,64}$`) and skip the existence check (let `restic restore` fail naturally with a clear error if the ID doesn't exist). This avoids listing all snapshots entirely.
+
+---
+
+### H5. No pruning for cross-drive restic repos (backup/crossdrive.go)
+
+**File:** `internal/backup/crossdrive.go`
+
+**Problem:** Cross-drive restic backups accumulate snapshots forever. Main backups have pruning via `restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6`, but cross-drive repos don't.
+
+**Fix:** After a successful cross-drive restic backup, run a prune step similar to the main backup. Add a `pruneRepo(ctx, repoPath, pwFile string)` function that runs `restic forget --keep-daily 7 --keep-weekly 4 --prune` on the cross-drive repo. Call it after backup in `runResticBackup()`.
+
+---
+
+### H6. Temp password file management (backup/crossdrive.go)
+
+**File:** `internal/backup/crossdrive.go`, lines 230-240
+
+**Problem:** `defer os.Remove(pwFile.Name())` is registered before the file is closed. On some systems this can fail. Also, no `defer pwFile.Close()` — the explicit `Close()` at line 240 won't run if code panics between creation and close.
+
+**Fix:** Reorganize:
+```go
+pwFile, err := os.CreateTemp("", "felhom-crossdrive-pw-*")
+if err != nil { return ... }
+pwPath := pwFile.Name()
+if _, err := pwFile.WriteString(password); err != nil {
+    pwFile.Close()
+    os.Remove(pwPath)
+    return ...
+}
+pwFile.Close()
+defer os.Remove(pwPath)
+```
+
+---
+
+### H7. `dirSizeBytes` swallows all walk errors (backup/crossdrive.go)
+
+**File:** `internal/backup/crossdrive.go`, lines 297-307
+
+**Problem:** `filepath.Walk` callback returns `nil` on error, hiding permission/IO issues.
+
+**Fix:** Return the error (or at least log it):
+```go
+err := filepath.Walk(path, func(_ string, info os.FileInfo, err error) error {
+    if err != nil {
+        return err // propagate instead of swallowing
+    }
+    if !info.IsDir() {
+        total += info.Size()
+    }
+    return nil
+})
+```
+
+---
+
+### H8. Non-atomic fstab write (storage/safety_linux.go)
+
+**File:** `internal/storage/safety_linux.go`, lines 91-102
+
+**Problem:** `AppendFstabEntry` writes directly to `/etc/fstab`. A crash during write corrupts the file, potentially bricking the system on reboot.
+
+**Fix:** Read fstab, append entry, write to `/etc/fstab.tmp`, then `os.Rename("/etc/fstab.tmp", "/etc/fstab")`. This is the same atomic pattern used in settings.go.
+
+---
+
+### H9. `IsDeviceMounted` naive prefix matching (storage/safety_linux.go)
+
+**File:** `internal/storage/safety_linux.go`, line 54
+
+**Problem:** `strings.HasPrefix(fields[0], devicePath)` causes `/dev/sdb` to match `/dev/sdb1`, `/dev/sdb2`, etc. — and worse, `/dev/sdb` matches `/dev/sdba` (hypothetical).
+
+**Fix:** After the prefix check, verify the next character is either end-of-string or a digit (for partition suffixes):
+```go
+src := fields[0]
+if src == devicePath || (strings.HasPrefix(src, devicePath) && len(src) > len(devicePath) && (src[len(devicePath)] >= '0' && src[len(devicePath)] <= '9' || src[len(devicePath)] == 'p')) {
+    return true, nil
+}
+```
+Or better: just check exact match for the device, and separately check if any partition of it is mounted.
+
+---
+
+### H10. eMMC device mapping bug (storage/scan_linux.go)
+
+**File:** `internal/storage/scan_linux.go`, lines 161-176
+
+**Problem:** `partitionToParentDisk` strips trailing digits to find the parent. For eMMC (`mmcblk0p1`), it strips `0p1` → `mmcblk` instead of correctly producing `mmcblk0`. The `p` separator between device number and partition number is not handled.
+
+**Fix:** Add eMMC/NVMe pattern detection:
+```go
+func partitionToParentDisk(partName string) string {
+    // Handle mmcblk0p1, nvme0n1p1 patterns (separator is "p" before partition number)
+    if idx := strings.LastIndex(partName, "p"); idx > 0 {
+        prefix := partName[:idx]
+        suffix := partName[idx+1:]
+        if len(suffix) > 0 && suffix[0] >= '0' && suffix[0] <= '9' {
+            // Check if prefix ends with a digit (e.g., mmcblk0, nvme0n1)
+            if prefix[len(prefix)-1] >= '0' && prefix[len(prefix)-1] <= '9' {
+                return prefix
             }
         }
-        next:
     }
-    return filtered
+    // Default: strip trailing digits (sda1 → sda)
+    return strings.TrimRight(partName, "0123456789")
 }
 ```
 
-**2. Auto-stop/restart in RestoreApp** (`internal/backup/restore.go`)
+---
 
+### H11. Data race on `bytesCopied` in rsync error path (storage/migrate.go)
+
+**File:** `internal/storage/migrate.go`, around line 243
+
+**Problem:** In `runRsync`, the `bytesCopied` variable is read (in the error return path) without holding the mutex, while a goroutine may be writing to it.
+
+**Fix:** Acquire the lock before reading `bytesCopied` in the error path, or use `atomic.Int64` instead of a mutex-protected variable.
+
+---
+
+### H12. Goroutine leak in rsync stdout reader (storage/migrate.go)
+
+**File:** `internal/storage/migrate.go`, lines 214-237
+
+**Problem:** A goroutine reads rsync's stdout. If the main function returns early (e.g., on context cancellation), the goroutine may block on `scanner.Scan()` forever if stdout isn't closed, or try to send on a closed channel.
+
+**Fix:** Ensure the goroutine exits cleanly:
+1. Use `cmd.StdoutPipe()` and ensure it's closed on function exit
+2. Use a `done` channel or context cancellation to signal the goroutine
+3. Don't send on the progress channel after function returns — use a select with a done channel
+
+---
+
+### H13. Path prefix match without separator (storage/migrate.go)
+
+**File:** `internal/storage/migrate.go`, lines 128-131
+
+**Problem:** `strings.HasPrefix(stackMount, currentHDD)` causes `/mnt/hdd` to match `/mnt/hdd_backup/data`. Stacks on a similarly-named but different mount would be migrated incorrectly.
+
+**Fix:** Append a trailing separator:
 ```go
-func (m *Manager) RestoreApp(stackName, snapshotID string) error {
-    // ... existing validation ...
-    
-    // Stop the app's containers before restore
-    if m.stackProvider != nil {
-        m.logger.Printf("[INFO] Stopping %s for restore...", stackName)
-        if err := m.stackProvider.StopStack(stackName); err != nil {
-            m.logger.Printf("[WARN] Could not stop %s: %v (proceeding anyway)", stackName, err)
-        }
-    }
-    
-    // Execute restore (existing logic)
-    if err := m.restic.RestoreAppData(snapshotID, hddMounts); err != nil {
-        // Try to restart even on failure
-        m.stackProvider.StartStack(stackName)
-        return err
-    }
-    
-    // Restart after successful restore
-    if m.stackProvider != nil {
-        m.logger.Printf("[INFO] Restarting %s after restore...", stackName)
-        m.stackProvider.StartStack(stackName)
-    }
-    
-    return nil
+if strings.HasPrefix(stackMount, currentHDD + "/") || stackMount == currentHDD {
+```
+
+---
+
+### H14. `DeleteStack` continues after failed `docker compose down` (stacks/delete.go)
+
+**File:** `internal/stacks/delete.go`, lines 88-92
+
+**Problem:** If `docker compose down` fails, the function continues to delete stack files and HDD data. This can leave orphaned containers running while their config is deleted.
+
+**Fix:** Return the error from `docker compose down` failure. If the user wants to force-delete, that should be a separate explicit option.
+
+---
+
+### H15. XSS in flash messages (web/handlers.go)
+
+**File:** `internal/web/handlers.go`, around lines 282-288
+
+**Problem:** URL query parameters (`?success=...`, `?error=...`) are passed to template data. If templates render these with `{{.}}` instead of escaping, it's XSS. Go's `html/template` auto-escapes in HTML context, but check if any use `{{. | safeHTML}}` or JavaScript context.
+
+**Fix:** Verify all flash message rendering uses standard `{{.Success}}` / `{{.Error}}` in HTML context (which Go auto-escapes). If any template uses these values inside `<script>` tags or `onclick` attributes, switch to JSON encoding or remove the pattern. Consider using session-based flash messages instead of URL params to prevent reflected XSS entirely.
+
+---
+
+### H16. `exec.Command("docker")` without timeout (web/handlers.go)
+
+**File:** `internal/web/handlers.go`, around lines 1247-1253
+
+**Problem:** `syncFileBrowserMounts()` runs `docker compose up -d` without a context timeout. Can hang indefinitely.
+
+**Fix:** Use `exec.CommandContext` with a 60-second timeout.
+
+---
+
+### H17. `SetNotificationPrefs` stores caller's pointer (settings/settings.go)
+
+**File:** `internal/settings/settings.go`, around line 219
+
+**Problem:** `s.data.NotificationPrefs = prefs` stores the caller's pointer/struct directly. If the caller later modifies the struct, it mutates settings state without going through the mutex.
+
+**Fix:** Deep-copy the prefs:
+```go
+func (s *Settings) SetNotificationPrefs(prefs NotificationPrefs) {
+    s.mu.Lock()
+    defer s.mu.Unlock()
+    copy := prefs // value copy
+    copy.EnabledEvents = make([]string, len(prefs.EnabledEvents))
+    copy(copy.EnabledEvents, prefs.EnabledEvents)
+    s.data.NotificationPrefs = copy
+    s.saveLocked()
 }
 ```
 
-### Frontend changes
+---
 
-**3. Template simplification** (`backups.html` Section 7)
-- Remove `restore-paths` div entirely
-- Replace warning text with single concise block
-- Keep app dropdown + snapshot dropdown + confirm checkbox + button
-- Update `onRestoreAppChange()` JS to call `/api/backup/snapshots?stack={name}`
+### H18. `wipefs` error silently discarded (storage/format_linux.go)
 
-**4. Snapshot display format**
-- Show: `2026-02-17 vasárnap 03:00` instead of `a3f2b1 — 2026.02.17. 3:00:00`
-- Keep snapshot ID in `option.value`, show human time in label
+**File:** `internal/storage/format_linux.go`, line 74
+
+**Problem:** `_ = exec.Command("wipefs", ...).Run()` discards the error. If `wipefs` fails, stale filesystem signatures remain, causing `mkfs.ext4` or mount to misbehave.
+
+**Fix:** Check the error. If `wipefs` fails, log a warning but continue (some systems don't have `wipefs`). At minimum don't use `_ =`:
+```go
+if err := exec.Command("wipefs", "-a", partPath).Run(); err != nil {
+    log.Printf("[WARN] wipefs failed on %s: %v (continuing)", partPath, err)
+}
+```
 
 ---
 
-## Design Decisions
+### H19. Orphaned fstab entry on mount failure (storage/format_linux.go)
 
-**D1: Snapshot dropdown format** → Show `date (id)` — human-friendly time with short ID in parentheses for support debugging. E.g. `2026-02-17 vasárnap 03:00 (a3f2b1)`
+**File:** `internal/storage/format_linux.go`, lines 140-150
 
-**D2: Zero filtered snapshots** → Show inline message instead of empty dropdown: "Még nincs mentés felhasználói adattal." (shortened from original)
+**Problem:** If fstab entry is written but the subsequent `mount` command fails, an orphaned entry remains in fstab. On next reboot, the system may hang waiting for a mount that doesn't work.
 
-**D3: Auto-stop/restart** → Yes, stacks must be stopped during restore. Check if StackProvider interface already exposes Stop/Start; extend it if not.
-
-**D4: Progress indication** → Keep current simple behavior (button text change + page redirect) for v0.13.0. Async polling (like backup progress) is a future enhancement.
-
-**D5: Restore scope** → User data (HDD paths) only. Docker configs and DB dumps are NOT restored — that's a disaster recovery task handled via CLI/support.
+**Fix:** If mount fails after fstab write, remove the fstab entry as rollback. Read fstab, remove the line containing the UUID, write back atomically.
 
 ---
 
-## Files to modify
+## MEDIUM Fixes
 
-| File | Changes |
-|------|---------|
-| `internal/web/api_router.go` (or `router.go`) | Add `?stack=` filter to snapshots endpoint |
-| `internal/backup/restore.go` | Add auto-stop/restart logic |
-| `internal/backup/types.go` | Add `filterSnapshotsByPaths` helper if needed |
-| `internal/web/templates/backups.html` | Simplify restore section HTML |
-| `internal/web/templates/backups.html` (JS) | Update `onRestoreAppChange()` to pass stack param |
-| `internal/stacks/` (maybe) | Ensure StackProvider exposes Stop/Start if needed for Q3 |
+### M1. `formatBytes` duplicate in dbdump.go (backup/dbdump.go)
 
-## Estimated effort
-- Backend: ~2 hours (snapshot filtering + auto-stop/restart + interface extension)
-- Frontend: ~1 hour (template simplification + JS update)
-- Testing: ~1 hour (restore flow with different apps/snapshots)
\ No newline at end of file
+**File:** `internal/backup/dbdump.go`, lines 467-483
+
+**Problem:** Duplicates `humanizeBytes()` from `appdata.go`.
+
+**Fix:** Delete `formatBytes()` from dbdump.go and replace all calls with `humanizeBytes()` from appdata.go.
+
+---
+
+### M2. Dead code `.tmp` suffix check (backup/dbdump.go)
+
+**File:** `internal/backup/dbdump.go`, lines 331-332
+
+**Problem:** Line 328 already filters for `.sql` suffix, so `.tmp` check is unreachable.
+
+**Fix:** Remove the dead `.tmp` check. If intent was to skip `.sql.tmp` files, fix the filter order: check `.tmp` before `.sql`.
+
+---
+
+### M3. `sizeBytes()` returns 0 for string types (storage/scan_linux.go)
+
+**File:** `internal/storage/scan_linux.go`, lines 33-39
+
+**Problem:** `lsblk` can return size as a string. The function only handles `float64` from JSON unmarshaling.
+
+**Fix:** Add string handling:
+```go
+case string:
+    n, _ := strconv.ParseUint(v, 10, 64)
+    return n
+```
+
+---
+
+### M4. Missing `PARTUUID=` handling in fstab (storage/scan_linux.go)
+
+**File:** `internal/storage/scan_linux.go`, lines 130-134
+
+**Problem:** `getSystemDiskNames` only parses `UUID=` entries from fstab, missing `PARTUUID=` entries common on Raspberry Pi.
+
+**Fix:** Add a `PARTUUID=` case that uses `blkid -t PARTUUID=xxx -o device` to resolve to a device path.
+
+---
+
+### M5. Inconsistent rollback in migration (storage/migrate.go)
+
+**File:** `internal/storage/migrate.go`, lines 160-163
+
+**Problem:** If `updateFn` fails (the callback that updates app config to point to new path), the data has been copied but the config still points to old path. No cleanup of copied data on target.
+
+**Fix:** If `updateFn` fails, attempt to clean up the target directory and return a clear error explaining the situation.
+
+---
+
+### M6. Dead `elapsed` variable (storage/migrate.go)
+
+**File:** `internal/storage/migrate.go`, around line 177
+
+**Problem:** `elapsed` is calculated but never used.
+
+**Fix:** Remove or use it in a log message.
+
+---
+
+### M7. `time.LoadLocation` error silently discarded (web/handlers.go)
+
+**File:** `internal/web/handlers.go`, lines 449-450, 541-542
+
+**Problem:** `loc, _ := time.LoadLocation("Europe/Budapest")` — if tzdata is missing, `loc` is nil causing panic on `time.Now().In(loc)`.
+
+**Fix:** Handle the error:
+```go
+loc, err := time.LoadLocation("Europe/Budapest")
+if err != nil {
+    loc = time.UTC
+    log.Printf("[WARN] timezone Europe/Budapest not available: %v", err)
+}
+```
+
+---
+
+### M8. "Run all" triggers manual-schedule backups (api/router.go)
+
+**File:** `internal/api/router.go`, lines 701-703
+
+**Problem:** The "run all" endpoint calls `RunAllScheduled(ctx, "manual")` or iterates all configs. If the intent of "manual" schedule was "only run when explicitly triggered per-app", running all defeats this.
+
+**Fix:** Clarify intent. If "Run all" should only trigger daily+weekly configs, filter out manual ones. If manual should also be included in "run all", document this behavior.
+
+---
+
+### M9. Background goroutines use `context.Background()` (api/router.go)
+
+**File:** `internal/api/router.go`, lines 658-662, 693-704
+
+**Problem:** Background goroutines for backup/restore use `context.Background()` and survive server shutdown, potentially corrupting data.
+
+**Fix:** Use a server-level context that's cancelled on shutdown. Pass the server's context (from `http.Server.BaseContext` or a custom one) and derive goroutine contexts from it.
+
+---
+
+### M10. `filterSnapshotsByPaths` imprecise prefix (api/router.go)
+
+**File:** `internal/api/router.go`, lines 476-490
+
+**Problem:** `strings.HasPrefix(snapPath, reqPath)` causes `/mnt/hdd_1` to match `/mnt/hdd_10/data`.
+
+**Fix:** Append separator: `strings.HasPrefix(snapPath, reqPath + "/") || snapPath == reqPath`.
+
+---
+
+### M11. XSS in `editStorageLabel` innerHTML (templates/settings.html)
+
+**File:** `internal/web/templates/settings.html`, around lines 280-296
+
+**Problem:** `cancelEditLabel` function uses `innerHTML` to restore label content. If `path` or `currentLabel` contain HTML, it's XSS.
+
+**Fix:** Use `textContent` instead of `innerHTML`:
+```javascript
+el.textContent = currentLabel || path;
+```
+
+---
+
+### M12. `GetNotificationPrefs` leaks slice reference (settings/settings.go)
+
+**File:** `internal/settings/settings.go`, around line 196
+
+**Problem:** Returns direct reference to `DefaultEnabledEvents` slice. Caller can modify the global default.
+
+**Fix:** Return a copy of the slice:
+```go
+events := make([]string, len(DefaultEnabledEvents))
+copy(events, DefaultEnabledEvents)
+```
+
+---
+
+### M13. `CheckBackupDestination` tier priority (system/mounts_linux.go)
+
+**Problem:** Tier 4 (disk full) overwrites Tier 3 (system drive) warning. If a drive is both the system drive and >90% full, only the disk-full warning shows.
+
+**Fix:** Accumulate warnings instead of overwriting. Return a slice of warnings, or use the highest severity.
+
+---
+
+### M14. Hardcoded paths in backup.go
+
+**File:** `internal/backup/backup.go`, lines 245-248, 524, 683
+
+**Problem:** `/opt/docker/felhom-controller/controller.yaml` is hardcoded in 3 places.
+
+**Fix:** Add a constant or derive from `m.cfg.Paths.DataDir`:
+```go
+const controllerYAMLPath = "/opt/docker/felhom-controller/controller.yaml"
+```
+Or better: `filepath.Join(m.cfg.Paths.DataDir, "controller.yaml")`.
+
+---
+
+## Testing Notes
+
+After making fixes:
+1. **Build:** `go build ./...` from the `controller/` directory must succeed
+2. **Vet:** `go vet ./...` must pass
+3. **Key areas to manually verify:**
+   - Storage format/mount still works (C5, C6, H8, H9, H18, H19)
+   - Backup cycle completes (C1-C4, H1-H7)
+   - Migration works (H11-H13, M5)
+   - Web UI loads without errors (H15, M11)
+
+## Post-Fix Checklist
+
+- [ ] Add `CHANGELOG.md` entry (session 39, v0.12.3) listing all fixes
+- [ ] Update `controller/README.md` if any API behavior changed
+- [ ] `go build ./...` passes
+- [ ] `go vet ./...` passes
diff --git a/controller/README.md b/controller/README.md
index 86a5c32..f1ee41c 100644
--- a/controller/README.md
+++ b/controller/README.md
@@ -2,76 +2,31 @@
 
 **Central management container for Felhom home servers.**
 
-Replaces Portainer + scattered systemd scripts with a single, lightweight container that provides:
-- Hungarian-language web dashboard for customers
-- Docker Compose stack management (start/stop/update)
-- Interactive first-deployment flow with auto-generated secrets
-- Health-aware container state monitoring (starting/unhealthy/running)
-- Backup orchestration (DB dumps + restic snapshots) — Phase 3
-- System health monitoring with Healthchecks pings — Phase 2
-- Git-based stack synchronization with update management — Phase 4
-- Self-update with automatic rollback on failure — Phase 5
+A single, lightweight Go container that replaces Portainer + scattered systemd scripts with a unified, Hungarian-language web dashboard for managing Docker Compose stacks, backups, storage, monitoring, and notifications on customer hardware.
 
-## Current Status
+**Current version: v0.12.2**
 
-**Phase 1 — Stack Manager + Deploy Flow: ✅ COMPLETE**
+---
 
-The controller is built, deployed, and running on the N100 test node (demo-felhom.eu).
-First application (Paperless-ngx) successfully deployed end-to-end through the dashboard on 2026-02-13.
+## Table of Contents
 
-**Milestone achieved:** Full deploy cycle works — customer clicks "Telepítés", fills in fields,
-controller generates secrets, saves app.yaml, runs `docker compose up -d`, and the app comes up
-with Traefik routing and health checks. The dashboard correctly shows real-time container states
-including health substatus (starting → healthy → running).
+- [Architecture](#architecture)
+- [Features](#features)
+  - [App Management](#1-app-management)
+  - [Backup System](#2-backup-system)
+  - [Storage Management](#3-storage-management)
+  - [Monitoring & Health](#4-monitoring--health)
+  - [Notifications](#5-notifications)
+  - [Update Management](#6-update-management)
+  - [Authentication & Settings](#7-authentication--settings)
+  - [Central Hub](#8-central-hub-reporting)
+- [Repository Layout](#repository-layout)
+- [Configuration](#configuration)
+- [REST API](#rest-api)
+- [Build & Deploy](#build--deploy)
+- [Roadmap](#roadmap)
 
-Current version: **v0.12.2**
-
-### What works
-- Dashboard with live container state (green/orange/yellow/red)
-- Deploy form with password validation, auto-generation, and field locking
-- Stack operations: start, stop, restart, update (pull + recreate)
-- Live-scrolling log viewer with auto-refresh (3s polling), pause/resume, and scroll position tracking
-- Deploy page doubles as config viewer (read-only mode for deployed apps)
-- App detail/info pages with use cases, setup guide, screenshots, and optional config
-- Optional config saves to `app.yaml` and restarts deployed apps (e.g., metadata provider API keys)
-- Periodic stack rescanning (every 2 minutes)
-- Manual rescan endpoint (`POST /api/stacks/rescan`)
-- Alphabetically sorted stack display (consistent card ordering)
-- Protected stacks (traefik, cloudflared, felhom-controller) can't be stopped
-- System info bar on dashboard: RAM, SSD, and HDD usage with progress bars
-- Docker Compose memory limits enforced via `deploy.resources.limits.memory`
-- Pre-deploy memory validation (hard block on `mem_request` overcommit, soft warning on `mem_limit` overcommit)
-- Memory summary bar shown on deploy page before deployment
-- Felhom.eu logo SVG in sidebar and login page
-- Verbose debug logging with operation timing, post-start container state checks, and image pull detection
-- Clickable app cards on dashboard and applications pages (navigate to info page)
-- Memory bar with two-segment visualization on deploy page (committed vs new app allocation)
-- Deployment progress UI: 3-step progress panel with real-time health polling (config → containers → health check)
-- CPU usage bar with load average display (1/5/15 min)
-- Temperature display with colored indicator dot (thermal zone reading)
-- Central job scheduler replacing ad-hoc goroutines (periodic + daily jobs)
-- Healthchecks.io-compatible system health pings with retry logic
-- Database auto-discovery and dump (PostgreSQL/MariaDB via docker exec)
-- Restic backup with auto-password generation, snapshot, prune, stats
-- Backup status card on dashboard with manual "Mentés most" trigger button
-- Backup API endpoints: status query and manual trigger
-- SQLite metrics store (system + container metrics, 60s collection, 30-day retention)
-- Heartbeat ping (5-minute "I'm alive" signal to Healthchecks)
-- Weekly backup integrity check (restic check, Sunday 04:00)
-- Central hub reporting (periodic JSON push to felhom-hub service)
-- Notification preferences sync to hub (controller → hub on save + startup)
-- Notification system with email delivery via Resend API (hub relay)
-- Storage paths registry with auto-discovery, per-app HDD_PATH resolution, and multi-storage support
-- Storage management UI: add/remove paths, edit labels, set default, toggle schedulable
-- Per-app storage visibility: storage badges on stacks page, app details per storage path on settings page
-- Deploy dropdown with free space display and low-space warnings
-- Filesystem & disk info (ext4/btrfs, device, model) on settings page
-- Backup page storage context with per-app storage label badges
-
-### Known issues / next priorities
-- Cloudflare Tunnel + Traefik TLS: paperless.demo-felhom.eu works locally but shows "Not secure" (certificate chain not fully validated through tunnel)
-- No undo/delete for deployed apps yet
-- Dashboard theme doesn't yet match felhom.eu dark theme
+---
 
 ## Architecture
 
@@ -80,23 +35,27 @@ Current version: **v0.12.2**
 │  Customer Hardware (N100 mini PC / Raspberry Pi)                │
 │                                                                 │
 │  ┌──────────┐   ┌────────────────────────────────────────────┐  │
-│  │ Traefik  │   │  felhom-controller                         │  │
+│  │ Traefik  │   │  felhom-controller (privileged container)  │  │
 │  │ (reverse │──▶│                                            │  │
 │  │  proxy)  │   │  ┌──────────┐  ┌─────────────────────────┐│  │
 │  └──────────┘   │  │ Web UI   │  │ Stack Manager           ││  │
-│                 │  │ (HU dash │  │ (compose up/down/pull,  ││  │
-│  ┌──────────┐   │  │  board)  │  │  git sync, update mgmt) ││  │
+│                 │  │ (HU dash │  │ (compose ops, git sync,  ││  │
+│  ┌──────────┐   │  │  board)  │  │  deploy, delete, update) ││  │
 │  │cloudflared│   │  └──────────┘  └─────────────────────────┘│  │
 │  │ (tunnel) │   │  ┌──────────┐  ┌─────────────────────────┐│  │
-│  └──────────┘   │  │ Backup   │  │ Monitor & Pinger        ││  │
-│                 │  │ (db dump │  │ (healthchecks pings,    ││  │
-│  ┌──────────┐   │  │  restic) │  │  system metrics)        ││  │
+│  └──────────┘   │  │ Backup   │  │ Storage Manager         ││  │
+│                 │  │ (3-layer │  │ (disk scan, format,     ││  │
+│  ┌──────────┐   │  │  restic) │  │  mount, migrate)        ││  │
 │  │ App      │   │  └──────────┘  └─────────────────────────┘│  │
 │  │ stacks   │   │  ┌──────────┐  ┌─────────────────────────┐│  │
-│  │ (docker  │   │  │Scheduler │  │ REST API                ││  │
-│  │ compose) │   │  │(cron-like│  │ (for UI + remote mgmt)  ││  │
-│  └──────────┘   │  │  jobs)   │  └─────────────────────────┘│  │
-│                 │  └──────────┘                              │  │
+│  │ (docker  │   │  │Scheduler │  │ Monitor & Metrics       ││  │
+│  │ compose) │   │  │(cron-like│  │ (health, pings, SQLite  ││  │
+│  └──────────┘   │  │  jobs)   │  │  time-series, Chart.js) ││  │
+│                 │  └──────────┘  └─────────────────────────┘│  │
+│                 │  ┌──────────┐  ┌─────────────────────────┐│  │
+│                 │  │ Notify   │  │ REST API + Hub Reporter ││  │
+│                 │  │ (email)  │  │ (JSON push to hub)      ││  │
+│                 │  └──────────┘  └─────────────────────────┘│  │
 │                 └────────────────────────────────────────────┘  │
 └─────────────────────────────────────────────────────────────────┘
          │ pings              │ JSON push          │ git pull
@@ -105,416 +64,659 @@ Current version: **v0.12.2**
   (Healthchecks)        (central dashboard)  (stack definitions)
 ```
 
-## Repository Layout
+### Key Architecture Decisions
 
-This is the `controller/` subfolder of the `deploy-felhom-compose` repository.
+- **Pure Go, no frameworks** — stdlib `net/http` + `html/template`. Only external deps: `bcrypt`, `yaml.v3`, `modernc.org/sqlite` (pure Go, no CGO).
+- **Privileged container** — Required for disk operations (format, mount, fstab), `/dev` access, and Docker socket control.
+- **`/host-dev` indirection** — Docker overrides `/dev` with a tmpfs. The host's `/dev` is mounted at `/host-dev` to access block devices.
+- **`StackDataProvider` interface** — Breaks circular import between backup and stacks packages. Implemented by `stackAdapter` in `main.go`.
+- **Atomic file writes** — All persistent state (`settings.json`, `app.yaml`) written to `.tmp` then `os.Rename` for crash safety.
+- **`go:embed` templates** — All HTML/CSS/JS compiled into the binary. No runtime file dependencies.
+- **Europe/Budapest timezone** — All scheduled jobs, timestamps, and UI labels use Hungarian timezone.
 
-```
-controller/
-├── cmd/controller/main.go           # Entry point, wires all modules
-├── internal/
-│   ├── config/config.go             # YAML loader, validation, env overrides
-│   ├── stacks/
-│   │   ├── manager.go               # Stack scanning, compose ops, container status, debug logging
-│   │   ├── metadata.go              # Parse .felhom.yml app metadata
-│   │   └── deploy.go                # First-deploy flow: secret gen, app.yaml, compose up
-│   ├── sync/
-│   │   └── sync.go                  # Git sync: clone/pull app catalog, content-hash copy
-│   ├── api/router.go                # REST API endpoints
-│   ├── scheduler/
-│   │   └── scheduler.go             # Central job scheduler (Every, Daily, skip-if-running)
-│   ├── system/
-│   │   ├── info.go                  # SystemInfo struct
-│   │   ├── info_linux.go            # Linux: /proc/meminfo + statfs + loadavg + temperature
-│   │   ├── info_other.go            # Non-Linux stub
-│   │   ├── cpu_linux.go             # CPU collector (background /proc/stat sampling)
-│   │   ├── cpu_other.go             # CPU collector stub (non-Linux)
-│   │   ├── mounts_linux.go          # Mount point, disk usage, FS info (findmnt, sysfs)
-│   │   └── mounts_other.go          # Non-Linux stubs for mount/disk/FS functions
-│   ├── monitor/
-│   │   ├── pinger.go                # Healthchecks.io HTTP ping client
-│   │   └── healthcheck.go           # System health checks (disk, mem, CPU, temp, Docker)
-│   ├── backup/
-│   │   ├── backup.go                # Backup orchestrator (DB dumps + restic + prune + integrity)
-│   │   ├── dbdump.go                # Database auto-discovery + dump (pg_dump, mariadb-dump)
-│   │   └── restic.go                # Restic operations (init, snapshot, prune, check, stats)
-│   ├── metrics/
-│   │   ├── store.go                 # SQLite metrics storage (system + container, downsampled queries)
-│   │   ├── collector.go             # Background collector (60s interval, system + docker stats)
-│   │   ├── types.go                 # SystemSample, ContainerSample, StaticSystemInfo structs
-│   │   └── sysinfo.go              # Host-level static info (/proc, /etc)
-│   ├── notify/
-│   │   └── notifier.go              # Notification relay (hub → email), preferences sync, cooldowns
-│   ├── report/
-│   │   ├── types.go                 # Hub report JSON payload definitions
-│   │   ├── builder.go               # Builds report from system/stacks/backup/metrics state
-│   │   └── pusher.go                # HTTP POST to central hub (retry, Bearer auth)
-│   └── web/
-│       ├── server.go                # HTTP server, routing, static file serving
-│       ├── auth.go                  # Session auth, login/logout handlers
-│       ├── handlers.go              # Page handlers (dashboard, stacks, deploy, etc.)
-│       ├── funcmap.go               # Template function map (state colors, formatting)
-│       ├── embed.go                 # go:embed directive for templates
-│       ├── templates.go             # Felhom logo SVG constant
-│       └── templates/               # go:embed HTML/CSS files (Hungarian UI)
-│           ├── layout.html, dashboard.html, stacks.html, login.html
-│           ├── logs.html, deploy.html, app_info.html
-│           ├── settings.html, backups.html, monitoring.html
-│           └── style.css
-├── configs/
-│   ├── controller.yaml.example      # Full config reference (infrastructure only)
-│   └── example-felhom-metadata.yml  # .felhom.yml format reference
-├── scripts/hashpass.go              # Bcrypt password hash generator
-├── assets/                          # App logos + screenshots (gitignored, synced at build)
-├── docs/BUILDING.md                 # Container image build & registry guide
-├── Dockerfile                       # Multi-stage build (Go 1.22 + debian-slim)
-├── docker-compose.yml               # Controller's own compose definition
-├── Makefile                         # Build targets + asset sync
-└── go.mod
-```
+### Module Map
 
-## Module Overview
+| Module | Path | Responsibility |
+|--------|------|----------------|
+| **Config** | `internal/config/` | YAML loader, validation, `FELHOM_*` env overrides |
+| **Settings** | `internal/settings/` | Runtime-mutable `settings.json` (passwords, backup prefs, storage paths, notifications) |
+| **Stacks** | `internal/stacks/` | Compose operations, scanning, `.felhom.yml` metadata, deploy/delete flow |
+| **Sync** | `internal/sync/` | Git-based app catalog sync (clone/pull, content-hash copy) |
+| **Backup** | `internal/backup/` | 3-layer backup: DB dumps → restic snapshots → cross-drive copies, restore |
+| **Storage** | `internal/storage/` | Disk scanning (`lsblk`), partitioning (`sfdisk`), formatting (`mkfs.ext4`), mounting, data migration (`rsync`) |
+| **System** | `internal/system/` | System info (`/proc`), CPU collector, mount points, disk usage, FS info |
+| **Monitor** | `internal/monitor/` | Healthchecks.io pinger, system health checks |
+| **Metrics** | `internal/metrics/` | SQLite time-series store, system + container metric collection |
+| **Scheduler** | `internal/scheduler/` | Central job scheduler (periodic + daily, skip-if-running, panic recovery) |
+| **Notify** | `internal/notify/` | Email notifications via hub relay, preference sync, per-event cooldowns |
+| **Report** | `internal/report/` | Hub report builder + HTTP pusher (system, stacks, backup, health) |
+| **API** | `internal/api/` | REST JSON endpoints |
+| **Web** | `internal/web/` | Hungarian dashboard, auth, page handlers, template functions, alerts |
 
-| Module | Path | Status | Responsibility |
-|--------|------|--------|----------------|
-| **Config** | `internal/config/` | ✅ Done | Load & validate controller.yaml, env overrides |
-| **Stacks** | `internal/stacks/` | ✅ Done | Compose operations, scanning, metadata, deploy flow |
-| **API** | `internal/api/` | ✅ Done | REST endpoints (stacks, deploy, rescan, system info, health) |
-| **Settings** | `internal/settings/` | ✅ Done | Persistent settings (password, notifications, storage paths, app backup prefs) |
-| **System** | `internal/system/` | ✅ Done | System resource info (RAM, disk, CPU, temperature, load, mount points, FS info) |
-| **Web** | `internal/web/` | ✅ Done | Hungarian dashboard, auth, deploy pages, asset serving |
-| **Sync** | `internal/sync/` | ✅ Done | Git-based app catalog sync (clone/pull, content-hash copy) |
-| **Scheduler** | `internal/scheduler/` | ✅ Done | Central job scheduler (periodic + daily, skip-if-running) |
-| **Monitor** | `internal/monitor/` | ✅ Done | Healthchecks.io pings, system health checks |
-| **Metrics** | `internal/metrics/` | ✅ Done | SQLite time-series store, system + container collection |
-| **Notify** | `internal/notify/` | ✅ Done | Notification relay to hub, preferences sync, cooldown tracking |
-| **Report** | `internal/report/` | ✅ Done | Central hub push (JSON report builder + HTTP pusher) |
-| **Backup** | `internal/backup/` | ✅ Done | DB auto-discovery + dump, restic snapshots, prune, manual trigger |
+---
 
-## Stack Management
+## Features
 
-### How stacks get onto the machine
+### 1. App Management
 
-1. During initial setup, `deploy-felhom-compose.sh` clones the app catalog
-2. Compose files + `.felhom.yml` metadata land in `/opt/docker/stacks/<app>/`
-3. The controller periodically pulls from Git to detect changes (Phase 4)
+The controller manages Docker Compose stacks through a complete lifecycle: catalog sync, first-time deployment, runtime operations, and deletion.
 
-### First deployment flow (via dashboard)
+#### Git Sync (`internal/sync/`)
 
-1. Customer sees app card with "🚀 Telepítés" (Deploy) button
-2. Clicks → deploy page shows:
-   - **Auto-filled**: DOMAIN (from controller config), read-only
-   - **Auto-generated**: DB passwords, secret keys (shown as "✓ Generated")
-   - **User input**: HDD path, admin password, language, etc.
-   - **"🎲 Generálás"** button next to password fields
-3. Clicks "Telepítés" → `checkBeforeDeploy()` JS guard fetches live state from API first (prevents deploying if already deployed from another tab). Then controller:
-   - **Memory validation**: checks `mem_request` against available system RAM (see below)
-   - Validates all required fields (password fields must be explicitly filled or generated)
-   - Generates auto-secrets (DB passwords, hex keys)
-   - Saves `app.yaml` (env vars + locked fields list)
-   - **Updates in-memory state immediately** (so UI shows "deployed" during slow compose ops)
-   - Runs `docker compose up -d` with env vars injected
-   - On failure: reverts both in-memory state and disk (app.yaml `deployed: false`)
-4. **Progress UI** replaces the form with a 3-step progress panel:
-   - ✅ "Konfiguráció mentve" — shown immediately after API success
-   - ⏳ "Konténer(ek) indítása..." → ✅ when containers are up
-   - ⏳ "Alkalmazás inicializálása..." → ✅ when state = `running` (healthy)
-   - Polls `GET /api/stacks/{name}` every 3 seconds for real-time health status
-   - Handles: `running` (auto-redirect), `starting` (keep polling), `unhealthy` (warning), `exited` (error)
-   - Timeout after 120 seconds with informational message
-5. Post-deploy: locked fields (DB_PASSWORD, etc.) become read-only
-6. "Részletek" button opens deploy page in read-only mode showing current config
+The app catalog lives in a separate Git repository. The controller:
+- Shallow-clones the catalog on startup
+- Periodically fetches updates (configurable, default 15 min)
+- Copies only `docker-compose.yml` and `.felhom.yml` to the stacks directory
+- **Never overwrites** `app.yaml` or `.env` (user secrets are safe)
+- Uses SHA-256 content hashing — only writes files that actually changed
+- Triggers stack rescan after sync so the dashboard updates immediately
+- Manual sync via "Sablonok frissitese" button or `POST /api/sync`
 
-### Memory validation during deploy
+#### First-Time Deploy Flow
 
-Before deploying an app, the controller checks if there's enough RAM. This uses the Kubernetes-inspired `mem_request` / `mem_limit` model:
+1. Customer sees app card with "Telepites" button
+2. Deploy page shows auto-filled fields (domain), auto-generated secrets (DB passwords, hex keys), and user-configurable inputs (admin password, language, storage path)
+3. `checkBeforeDeploy()` JS guard fetches live state first (prevents double-deploy from another tab)
+4. **Memory validation** checks `mem_request` against available RAM:
+   - `usable_memory = total_ram - reserved_memory_mb` (default 384MB reserved)
+   - Hard block if requests exceed usable memory
+   - Soft warning if limits exceed total RAM (overcommit OK)
+5. Controller generates secrets, saves `app.yaml`, sets in-memory `Deployed` flag **before** `docker compose up -d` (avoids stale UI during slow image pulls), reverts on failure
+6. 3-step progress panel polls `GET /api/stacks/{name}` every 3s: config saved → containers starting → health check passed
+7. Post-deploy: locked fields (DB_PASSWORD, etc.) become read-only
 
-| Field | In `.felhom.yml` | Purpose | Validation |
-|-------|-------------------|---------|------------|
-| `mem_request` | `resources.mem_request: "500M"` | Expected memory usage during normal operation | **Hard block** — sum of requests must not exceed usable RAM |
-| `mem_limit` | `resources.mem_limit: "1152M"` | Docker `deploy.resources.limits.memory` total across all containers | **Soft warning** — overcommit is allowed for limits |
-| `pi_compatible` | `resources.pi_compatible: true` | Whether the app can run on Raspberry Pi | Display-only hint |
-| `needs_hdd` | `resources.needs_hdd: true` | Whether the app needs external storage | Display-only hint |
+#### App Info Pages
 
-**How it works:**
-- `usable_memory = total_ram - reserved_memory_mb` (default: 384MB reserved for OS + controller)
-- If `sum(deployed mem_requests) + new_mem_request > usable_memory` → deploy is **blocked** with error
-- If `sum(deployed mem_limits) + new_mem_limit > total_ram` → deploy proceeds with **warning**
-- Apps without `mem_request` set are treated as 0MB (never blocked)
-- The deploy page shows a memory summary bar before the user clicks deploy
+Each app can define rich metadata in `.felhom.yml`:
+- `app_info`: tagline, use_cases, first_steps, prerequisites, default_creds, docs_url
+- `optional_config`: groups of post-deploy configurable env vars (e.g., API keys for metadata providers)
+- `resources`: mem_request, mem_limit, pi_compatible, needs_hdd
 
-Configure the reserved memory via `controller.yaml`:
-```yaml
-system:
-  reserved_memory_mb: 384  # default
-```
+The `/apps/{slug}` page renders hero section, screenshots, setup guide, and optional config form.
 
-### Container state display
+#### Stack Operations
 
-The dashboard shows health-aware container states with distinct colors:
+| Operation | What it does |
+|-----------|-------------|
+| Start | `docker compose up -d` |
+| Stop | `docker compose stop` (blocked for protected stacks) |
+| Restart | `docker compose restart` |
+| Update | `docker compose pull` + `docker compose up -d` |
+| Delete | `docker compose down --rmi local --volumes` + optional HDD data cleanup |
+
+**Protected stacks** (traefik, cloudflared, felhom-controller) cannot be stopped or deleted from the UI. Restart is allowed.
+
+**Orphan detection**: Deployed stacks with no matching catalog template are marked as orphaned with an "Elavult" badge and can be safely deleted.
+
+#### Container State Display
 
 | State | Color | Label | Meaning |
 |-------|-------|-------|---------|
-| Running + healthy | 🟢 Green | "Fut" | All containers running and healthy |
-| Running + health: starting | 🟠 Orange | "Indulás..." | Container up but healthcheck not yet passed |
-| Running + unhealthy | 🟡 Yellow | "Nem egészséges" | Container running but healthcheck failing |
-| Stopped/exited | 🔴 Red | "Leállítva" | All containers stopped |
-| Restarting | 🟡 Yellow | "Újraindítás..." | Container in restart loop |
-| Not deployed | ⚪ Gray | "Nincs telepítve" | Compose file exists but not yet deployed |
+| Running + healthy | Green | "Fut" | All containers running and healthy |
+| Running + starting | Orange | "Indulas..." | Healthcheck not yet passed |
+| Running + unhealthy | Yellow | "Nem egeszseges" | Healthcheck failing |
+| Stopped/exited | Red | "Leallitva" | All containers stopped |
+| Restarting | Yellow | "Ujrainditas..." | Restart loop |
+| Not deployed | Gray | "Nincs telepitve" | Compose file exists, not deployed |
 
-Action buttons adapt: "operational" states (running/starting/unhealthy/restarting) show restart/stop,
-while stopped states show a start button.
+---
 
-### Update strategy (Phase 4)
+### 2. Backup System
 
-Stack updates are classified in the Git repository via markers:
+The backup system implements a 3-layer architecture ensuring data safety through redundancy and versioning.
+
+#### Layer 1: Database Dumps (`internal/backup/dbdump.go`)
+
+- **Auto-discovery** of PostgreSQL and MariaDB containers via `docker ps` + `docker inspect`
+- Dumps via `docker exec pg_dump` / `docker exec mariadb-dump` with 5-minute timeout
+- Atomic writes (`.tmp` → `.sql`) to prevent corruption
+- **Validation** after each dump: checks file size, header presence, counts `CREATE TABLE` statements
+- Results cached in `settings.json` surviving container restarts
+- Scheduled nightly at 02:30
+
+#### Layer 2: Restic Snapshots (`internal/backup/restic.go`)
+
+- Auto-generated repository password (32 random bytes, base64url)
+- Password synced to hub for disaster recovery
+- Backs up: stacks directory + DB dump directory + enabled app HDD mount paths
+- Auto-detects and unlocks stale locks
+- Weekly prune on Sundays with configurable retention (keep-daily, keep-weekly, keep-monthly)
+- Weekly integrity check (`restic check`) on Sunday 04:00
+- Scheduled nightly at 03:00 (runs after DB dumps complete)
+
+#### Layer 3: Cross-Drive Backup (`internal/backup/crossdrive.go`)
+
+Implements the 3-2-1 backup rule by copying data to a different physical drive.
+
+- **Two methods:**
+  - **rsync** — Simple mirror with `--delete` (fast, no versioning)
+  - **restic** — Versioned, deduplicated, encrypted (shared repo across apps)
+- Per-app configuration: destination path, method, schedule (daily/weekly/manual)
+- Safety guards: destination != source, mount point check, writable check
+- **Chained execution**: cross-drive runs immediately after nightly restic backup (daily apps every night, weekly apps on Sundays) for DB/file consistency
+- Per-app concurrency lock prevents overlapping runs
+- Status tracking (last_run, duration, size, error) persisted to settings.json
+
+#### Restore (`internal/backup/restore.go`)
+
+- Per-app restore from restic snapshots
+- Snapshot filtering by app: `GET /api/backup/snapshots?stack={name}` returns only snapshots whose paths overlap the app's HDD mounts
+- **Auto stop/restart**: stops the app's containers before `restic restore`, restarts after (even on failure)
+- Human-friendly snapshot display: `2026-02-17 hetfo 03:00 (a3f2b1)`
+- Running flag prevents concurrent backup/restore operations
+
+#### Backup Page UI
+
+The backups page shows a unified per-app status table:
+- **Status dot**: green (fully covered), yellow (warning — failed run, system drive, disk full), red (HDD data without cross-drive), auto (no user data)
+- Expandable row per app showing all 3 backup layers (DB, Docker volumes, user data)
+- Schedule overview with next run times
+- Snapshot history table (last 20 snapshots with ID, time, data added)
+- Repository info card (path, size, snapshot count, encryption key with show/copy)
+- Restore section with app/snapshot dropdowns and confirmation flow
+
+---
+
+### 3. Storage Management
+
+The storage subsystem handles the full lifecycle of external storage: detection, initialization, path registration, and data migration.
+
+#### Disk Scanning (`internal/storage/scan.go`)
+
+- `ScanDisks()` uses `lsblk -J -b` for block device enumeration
+- System disk detection via host fstab parsing (`/host-fstab`) + UUID resolution via `blkid`
+- Partitions enriched with filesystem type, UUID, and label from direct `blkid` probing (Docker containers have incomplete udev cache)
+- Returns `AvailableDisks` (non-system, non-loop, non-CDROM) and `SystemDisks` separately
+- Handles NVMe (`nvme0n1p1`), SCSI (`sdb1`), and eMMC (`mmcblk0p1`) naming
+
+#### Disk Initialization Wizard (`internal/storage/format.go`)
+
+A step-by-step UI at `/settings/storage/init`:
+
+1. **Scan** — Lists available disks with model, size, partition info
+2. **Select** — User picks a disk and enters a mount name (e.g., `hdd_1`)
+3. **Confirm** — User types "FORMAZAS" to confirm destructive operation
+4. **Format pipeline**: `wipefs` → `sfdisk` (GPT) → `mkfs.ext4` → `blkid` UUID → backup fstab → append UUID-based fstab entry → mount → `findmnt` verification → `chown 1000:1000` → create `storage/` and `Dokumentumok/` subdirectories
+5. Auto-registers new storage path in settings.json
+6. Smart partition detection: skips repartitioning for existing empty partitions
+
+Safety guards: system disk detection, mount path conflict check, confirmation required, progress channel for real-time UI feedback.
+
+#### Storage Path Registry (`internal/settings/settings.go`)
+
+Multiple external storage paths supported with:
+- **Label**: Human-readable name (editable inline)
+- **Default flag**: New deploys use this path by default
+- **Schedulable flag**: Path appears in deploy dropdown
+- **Auto-discovery**: On startup, scans deployed apps' `HDD_PATH` values and registers unknown paths
+- Thread-safe CRUD: Add, Remove, SetDefault, SetSchedulable, SetLabel
+
+#### Data Migration (`internal/storage/migrate.go`)
+
+Move app data between storage paths (e.g., SSD → HDD, HDD → new HDD):
+
+1. Validate: stack exists, deployed, has HDD data, target differs from source
+2. Estimate total size, check free space on target
+3. Stop the application
+4. `rsync -a --info=progress2` per mount path with real-time progress parsing
+5. Update `app.yaml` HDD_PATH to new location
+6. Start the application
+7. **Rollback on failure**: reverts config, restarts on old storage
+
+Progress UI at `/stacks/{name}/migrate` with byte counter and percentage.
+
+#### Stale Data Cleanup
+
+After migration, the deploy page detects leftover data on previous storage paths:
+- Shows path, size, and a delete button
+- Two-step confirmation required
+- Protected paths (storage root, media, Dokumentumok, appdata) cannot be deleted
+
+#### FileBrowser Mount Sync
+
+When storage paths are added or removed, `syncFileBrowserMounts()` auto-regenerates FileBrowser's `docker-compose.yml` with volume mounts for all registered paths, then recreates the container.
+
+---
+
+### 4. Monitoring & Health
+
+#### System Health Checks (`internal/monitor/healthcheck.go`)
+
+`RunHealthCheck()` evaluates multiple subsystems and returns a `HealthReport` with status (`ok`/`warn`/`fail`):
+
+| Check | Warning | Critical |
+|-------|---------|----------|
+| Disk usage (SSD/HDD) | >= 90% | >= 95% |
+| Memory | available < 512MB | available < 256MB |
+| CPU temperature | >= 75C | >= 85C |
+| Docker daemon | — | unreachable |
+| Protected containers | — | not running |
+| Storage paths | not a mount point (data on SSD) | path inaccessible, disk >= 95% |
+
+Backup destination validation (`CheckBackupDestination`) has tiered checks:
+- Path doesn't exist → critical/blocked
+- Not writable → critical/blocked
+- Same block device as root → warning (data on system drive)
+- Disk >95% full → critical/blocked
+- Disk >90% full → warning
+
+#### Healthchecks.io Integration (`internal/monitor/pinger.go`)
+
+Five ping UUIDs for external monitoring:
+- **Heartbeat**: every 5 min (simple "I'm alive")
+- **System Health**: periodic health check results
+- **DB Dump**: after nightly database dumps
+- **Backup**: after nightly restic backup
+- **Backup Integrity**: weekly `restic check` result
+
+3-attempt retry with 2-second backoff. Pinger never fails the caller.
+
+#### Metrics Store (`internal/metrics/`)
+
+- **SQLite with WAL mode** for concurrent reads during collection
+- **System metrics**: CPU%, memory (total/used/available), temperature, load average — collected every 60 seconds
+- **Container metrics**: CPU%, memory, network I/O, block I/O per container
+- Downsampled queries for chart time ranges (1h, 6h, 24h, 7d, 30d)
+- 30-day auto-prune via daily scheduler job
+
+#### Monitoring Page
+
+Full-page system monitor at `/monitoring`:
+- **System Overview**: hostname, OS, kernel, CPU model/cores, uptime
+- **System Metrics Charts**: 4 line charts (CPU, Memory, Temperature, Load) in 2x2 grid
+- **Container Resources**: horizontal bar charts (CPU% and Memory per container)
+- **Per-container Detail**: click-to-expand historical charts
+- **Remote Monitoring Status**: shows Healthchecks ping UUID configuration
+
+Chart.js 4.4.7 embedded locally (works in offline environments), dark theme matching site design.
+
+#### Alert System (`internal/web/alerts.go`)
+
+State-based alerts displayed on all pages:
+- Sources: health issues, missing ping UUIDs, backup disabled
+- Sorted by severity (error > warning > info), capped at 5 visible
+- Refreshed every 5 min + on startup
+- Monitoring page suppresses ping-related alerts (shown in dedicated table instead)
+
+---
+
+### 5. Notifications
+
+#### Email Delivery
+
+The controller relays notifications through the central hub, which sends emails via the Resend API:
+1. Controller detects event (health degradation, backup failure, etc.)
+2. Non-blocking POST to hub's `/api/v1/notify` with event details
+3. Hub checks customer notification preferences
+4. Hub sends Hungarian-language email via Resend
+
+#### Event Types
+
+| Event | Trigger |
+|-------|---------|
+| `disk_warning` | Disk usage crosses warning/critical threshold |
+| `backup_failed` | Nightly backup or DB dump fails |
+| `update_available` | New app version detected in catalog |
+| `security_update` | Critical security update available |
+
+#### Cooldown System
+
+Per-event-type cooldown (default 6 hours, configurable) prevents notification spam. Only notifies on **status degradation** (ok→warn, ok→fail, warn→fail), not on repeated same-status checks.
+
+#### Preference Sync
+
+Notification preferences (email, enabled events, cooldown) are:
+- Stored locally in `settings.json`
+- Synced to hub on save and on controller startup
+- Hub sync failure doesn't block local save
+
+---
+
+### 6. Update Management
+
+#### App Catalog Sync
+
+- Periodic `git fetch` + `git reset --hard` of the app catalog repo
+- Content-hash comparison prevents unnecessary file writes
+- Post-sync stack rescan detects new/changed apps immediately
+
+#### Planned Update Classifications
 
 | Marker | Behavior |
 |--------|----------|
-| No marker | Optional update — shown on dashboard, customer clicks "Update" |
+| No marker | Optional — shown on dashboard, customer clicks "Update" |
 | `UPDATE_REQUIRED=true` | Mandatory — auto-applied during next update window |
-| `UPDATE_SECURITY=true` | Critical — applied immediately (within minutes) |
+| `UPDATE_SECURITY=true` | Critical — applied immediately |
 
-### Protected stacks
+---
 
-The following stacks cannot be stopped from the customer UI:
-- `traefik` (reverse proxy)
-- `cloudflared` (tunnel)
-- `felhom-controller` (this container)
+### 7. Authentication & Settings
 
-## Logging
+#### Session Auth (`internal/web/auth.go`)
 
-The controller uses two-tier logging controlled by `logging.level` in `controller.yaml`:
+- bcrypt password verification with configurable source priority: `settings.json` → `controller.yaml` → no auth (open access)
+- 7-day session duration with random 32-byte hex tokens
+- `?next=` redirect after login preserves the page the user was visiting
+- Session cleanup every 15 minutes
+- All sessions invalidated on password change
+- Conditional logout link (hidden when auth is disabled)
 
-```yaml
-logging:
-  level: debug    # debug | info | warn | error (default: info)
-  file: ""        # optional log file path
-  max_size_mb: 10
-  max_files: 3
-```
+#### Settings Persistence (`internal/settings/settings.go`)
 
-Can also be set via environment variable: `FELHOM_LOGGING_LEVEL=debug`
+Runtime-mutable settings in `settings.json` (separate from infrastructure config):
 
-### What gets logged at each level
+| Section | Contents |
+|---------|----------|
+| `password_hash` | bcrypt hash override |
+| `notifications` | email, enabled events, cooldown hours |
+| `db_validations` | per-DB dump validation results (survives restarts) |
+| `app_backup` | per-app map: enabled flag, cross-drive config (method, dest, schedule, runtime status) |
+| `storage_paths` | registered paths with label, default flag, schedulable flag |
+| `cross_drive_restic_password` | auto-generated restic password for cross-drive repos |
 
-| Level | What's logged |
-|-------|--------------|
-| **info** | Operation success/failure with elapsed time, post-start container states, stack scan counts, deploy memory checks |
-| **debug** | All of above + env var keys per compose command, local image availability checks, compose command timing, log fetch byte counts |
+All public methods use `sync.RWMutex`. File writes are atomic (`.tmp` + rename).
 
-### Example output (debug level)
+#### Settings Page (`/settings`)
+
+Three sections:
+1. **System config** — read-only display of `controller.yaml` values
+2. **Password change** — current + new + confirm, min 8 chars
+3. **Storage paths** — add/remove, edit labels, set default, toggle schedulable, per-path app list with sizes
+4. **Notifications** — email, event checkboxes, cooldown hours, test email button
+
+---
+
+### 8. Central Hub Reporting
+
+#### Report Push (`internal/report/`)
+
+Periodic JSON push (default every 15 min) to the central felhom-hub service:
+- System: hostname, OS, CPU, memory, disk usage, uptime
+- Containers: running/stopped counts, per-container CPU/memory
+- Backup: last run, success, repo stats, snapshot count, restic password (for disaster recovery)
+- Health: current status, issues, warnings
+- Stacks: deployed apps with versions and states
+
+Bearer token authentication, 3-attempt retry with 5-second backoff.
+
+#### Hub Dashboard
+
+The hub service (separate Go app in the `felhom.eu` repo) provides:
+- Multi-customer overview table with status indicators
+- Customer detail page with system/storage/containers/backup/health sections
+- Color coding: green (<30min), yellow (30-60min), red (>60min since last report)
+- 90-day report retention with daily prune
+
+---
+
+## Repository Layout
 
 ```
-[INFO] Starting stack: immich
-[DEBUG] Env vars for compose: [DOMAIN, DB_PASSWORD, HDD_PATH] (3 app + 42 system)
-[DEBUG] Running: docker compose up -d (in /opt/docker/stacks/immich)
-[DEBUG] Command completed: docker compose up -d (took 12.3s)
-[INFO] Stack immich started successfully (took 12.3s)
-[INFO] Stack immich post-start status:
-[INFO]   immich-server   ghcr.io/immich-app/immich-server:release   running   Up 3 seconds (health: starting)
-[INFO]   immich-postgres docker.io/tensorchord/pgvecto-rs:pg16...   running   Up 3 seconds (healthy)
-[INFO]   immich-redis    docker.io/library/redis:7-alpine            running   Up 3 seconds (healthy)
+controller/
+├── cmd/controller/main.go           # Entry point, wires all 14 modules
+├── internal/
+│   ├── config/config.go             # YAML loader, validation, env overrides
+│   ├── settings/settings.go         # Runtime settings (JSON, atomic writes, RWMutex)
+│   ├── stacks/
+│   │   ├── manager.go               # Stack scanning, compose ops, container status
+│   │   ├── metadata.go              # Parse .felhom.yml app metadata
+│   │   ├── deploy.go                # First-deploy: secret gen, app.yaml, compose up
+│   │   └── delete.go                # Stack deletion + HDD data cleanup
+│   ├── sync/sync.go                 # Git sync: clone/pull app catalog, content-hash copy
+│   ├── storage/
+│   │   ├── scan.go, scan_linux.go   # Disk detection via lsblk + blkid
+│   │   ├── format.go, format_linux.go  # Partition, format, mount pipeline
+│   │   ├── safety.go, safety_linux.go  # System disk detection, mount guards, fstab ops
+│   │   ├── migrate.go              # App data migration (rsync with progress)
+│   │   └── *_other.go              # Non-Linux stubs for cross-compilation
+│   ├── backup/
+│   │   ├── backup.go               # Orchestrator (dumps + restic + cross-drive chain)
+│   │   ├── dbdump.go               # DB auto-discovery + dump (pg_dump, mariadb-dump)
+│   │   ├── restic.go               # Restic operations (init, snapshot, prune, check)
+│   │   ├── appdata.go              # StackDataProvider interface, app data discovery
+│   │   ├── crossdrive.go           # Per-app backup to secondary storage (rsync/restic)
+│   │   └── restore.go              # Per-app restore with auto stop/restart
+│   ├── api/router.go               # REST API endpoints (~30 routes)
+│   ├── scheduler/scheduler.go      # Central job scheduler (Every, Daily)
+│   ├── system/
+│   │   ├── info.go, info_linux.go  # RAM, disk, CPU, temperature, load average
+│   │   ├── cpu_linux.go            # Background /proc/stat sampling
+│   │   └── mounts_linux.go         # Mount points, disk usage, FS info, backup dest checks
+│   ├── monitor/
+│   │   ├── pinger.go               # Healthchecks.io HTTP ping client
+│   │   └── healthcheck.go          # System health checks (disk, mem, CPU, temp, Docker)
+│   ├── metrics/
+│   │   ├── store.go                # SQLite time-series (WAL mode, downsampled queries)
+│   │   ├── collector.go            # Background collector (60s, system + docker stats)
+│   │   └── sysinfo.go              # Static system info (/proc, /etc)
+│   ├── notify/notifier.go          # Email relay to hub, preference sync, cooldowns
+│   ├── report/
+│   │   ├── builder.go              # Hub report builder (all subsystems → JSON)
+│   │   └── pusher.go               # HTTP POST to hub (retry, Bearer auth)
+│   └── web/
+│       ├── server.go               # HTTP server, routing, static files
+│       ├── auth.go                 # Session auth, login/logout, session cleanup
+│       ├── handlers.go             # Page handlers (dashboard, stacks, deploy, backups, etc.)
+│       ├── storage_handlers.go     # Storage API handlers (scan, format, migrate, cleanup)
+│       ├── alerts.go               # State-based alert generation
+│       ├── funcmap.go              # Template functions (state colors, Hungarian formatting)
+│       ├── embed.go                # go:embed for templates + Chart.js
+│       └── templates/              # 12 HTML files + style.css (Hungarian UI)
+├── configs/
+│   ├── controller.yaml.example     # Full config reference
+│   └── example-felhom-metadata.yml # .felhom.yml format reference
+├── Dockerfile                      # Multi-stage: Go 1.24 builder + debian-slim runtime
+├── docker-compose.yml              # Controller's own compose (privileged, /mnt rshared)
+└── go.mod                          # Go 1.24, deps: bcrypt, yaml.v3, modernc.org/sqlite
 ```
 
-On failure:
-```
-[ERROR] Command failed: docker compose up -d (in /opt/docker/stacks/immich) — exit code 1 (took 2.1s)
-[ERROR] stderr: Error response from daemon: pull access denied...
-[ERROR] Stack immich start failed after 2.1s: exit code 1
-```
-
-### Security
-
-- Env var **values** are never logged — only keys appear in debug output
-- stdout/stderr in error logs are truncated to 500 characters to prevent log spam
+---
 
 ## Configuration
 
-### Controller config (infrastructure only)
+### Controller config (`controller.yaml`)
 
-Single YAML file per customer: `/opt/docker/felhom-controller/controller.yaml`
-
-Contains customer identity, infrastructure secrets, backup/monitoring settings.
-Does **not** contain app-specific config (HDD paths, DB passwords, etc.).
-
-See `configs/controller.yaml.example` for the full reference.
-
-### Per-app config (created during deployment)
-
-Each deployed app gets an `app.yaml` in its stack directory:
+Single YAML file per customer, infrastructure-only. Does **not** contain app-specific config.
 
+Key sections:
 ```yaml
-# /opt/docker/stacks/paperless-ngx/app.yaml
-# Auto-generated by felhom-controller — do not edit locked fields manually
-deployed: true
-deployed_at: "2026-02-13T21:10:00Z"
-env:
-  DOMAIN: "demo-felhom.eu"
-  DB_PASSWORD: "a7f2b9c1e4d..."       # locked
-  PAPERLESS_SECRET_KEY: "8b3e..."      # locked
-  PAPERLESS_ADMIN_USER: "admin"        # editable
-  PAPERLESS_OCR_LANGUAGE: "hun+eng"    # editable
-  HDD_PATH: "/mnt/hdd_placeholder"    # locked
-locked_fields:
-  - DB_PASSWORD
-  - PAPERLESS_SECRET_KEY
-  - DOMAIN
-  - HDD_PATH
+customer:
+  name: "Demo Felhom"
+  node_id: "demo-felhom"
+
+paths:
+  stacks_dir: "/opt/docker/stacks"
+  data_dir: "/opt/docker/felhom-controller/data"
+  db_dump_dir: "/srv/backups/db-dumps"
+  restic_repo: "/srv/backups/restic-repo"
+
+git:
+  repo_url: "https://gitea.dooplex.hu/admin/app-catalog-felhom.eu.git"
+  sync_interval: "15m"
+
+backup:
+  enabled: true
+  db_dump_time: "02:30"
+  restic_time: "03:00"
+  retention: { keep_daily: 7, keep_weekly: 4, keep_monthly: 6 }
+
+monitoring:
+  health_interval: "5m"
+  ping_uuids:
+    heartbeat: "uuid-here"
+    system_health: "uuid-here"
+    db_dump: "uuid-here"
+    backup: "uuid-here"
+    backup_integrity: "uuid-here"
+
+hub:
+  enabled: true
+  url: "https://hub.felhom.eu"
+  api_key: "bearer-token-here"
+
+system:
+  reserved_memory_mb: 384  # RAM reserved for OS + controller
 ```
 
-### App assets (logos, screenshots)
+Environment variable overrides: `FELHOM_LOGGING_LEVEL=debug`, `FELHOM_HUB_ENABLED=false`, etc.
 
-Baked into the container image at build time — no external dependencies at runtime.
-Synced from the felhom.eu website repo before building.
+### Runtime settings (`settings.json`)
 
-Served locally at `/static/assets/`. Logos try SVG first, fall back to PNG.
+Auto-managed by the controller. Contains password hash overrides, notification preferences, per-app backup configs, storage path registry, DB validation cache. All writes are atomic.
+
+### Per-app config (`app.yaml`)
+
+Auto-generated during deployment. Contains env vars, locked fields list, deploy timestamp. Secret fields are locked (read-only after first deploy).
+
+---
+
+## Scheduler Jobs
+
+| Job | Type | When | Purpose |
+|-----|------|------|---------|
+| status-refresh | periodic | 30s | Refresh container states |
+| stack-scan | periodic | 2m | Rescan stacks directory |
+| heartbeat | periodic | 5m | Ping Healthchecks "I'm alive" |
+| system-health | periodic | configurable | Health checks + alert refresh |
+| backup-cache | periodic | 5m | Refresh backup status cache |
+| hub-report | periodic | 15m | Push report to central hub |
+| db-dump | daily | 02:30 | Database dumps |
+| backup | daily | 03:00 | Restic backup → cross-drive chain |
+| backup-integrity | daily | Sun 04:00 | Restic check |
+| metrics-prune | daily | 04:00 | Delete metrics older than 30 days |
+
+All daily jobs use Europe/Budapest timezone. Skip-if-running prevents concurrent execution. Panic recovery in all jobs.
+
+---
+
+## REST API
+
+### Stack Operations
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/health` | Health check (no auth) |
+| GET | `/api/stacks` | List all stacks |
+| GET | `/api/stacks/{name}` | Stack details |
+| POST | `/api/stacks/{name}/deploy` | First-time deploy |
+| POST | `/api/stacks/{name}/start` | Start stack |
+| POST | `/api/stacks/{name}/stop` | Stop stack |
+| POST | `/api/stacks/{name}/restart` | Restart stack |
+| POST | `/api/stacks/{name}/update` | Pull + recreate |
+| POST | `/api/stacks/{name}/optional-config` | Update optional env vars |
+| GET | `/api/stacks/{name}/logs` | Container logs (`?raw=1` for plain text) |
+| GET | `/api/stacks/{name}/hdd-data` | HDD data paths + sizes |
+| DELETE | `/api/stacks/{name}` | Delete stack |
+| POST | `/api/sync` | Trigger catalog sync |
+| GET | `/api/system/info` | System info + sync status |
+
+### Backup & Restore
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/backup/status` | Full backup status |
+| POST | `/api/backup/run` | Trigger manual backup |
+| GET | `/api/backup/snapshots` | List snapshots (`?stack={name}` for filtering) |
+| POST | `/api/stacks/{name}/cross-backup` | Save cross-drive config |
+| POST | `/api/stacks/{name}/cross-backup/run` | Trigger cross-drive backup |
+| GET | `/api/stacks/{name}/cross-backup/status` | Cross-drive status |
+| POST | `/api/backup/cross-drive/run-all` | Run all scheduled cross-drive backups |
+
+### Storage
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/storage/scan` | Scan available disks |
+| POST | `/api/storage/init` | Format and mount a disk |
+| GET | `/api/storage/init/status` | Format progress |
+| POST | `/api/storage/migrate` | Start app data migration |
+| GET | `/api/storage/migrate/status` | Migration progress |
+
+### Metrics
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/metrics/system` | System metrics time-series (`?range=1h|6h|24h|7d|30d`) |
+| GET | `/api/metrics/containers/summary` | Current container stats |
+| GET | `/api/metrics/containers/{name}` | Per-container time-series |
+| GET | `/api/metrics/sysinfo` | Static system info |
+
+Response format: `{"ok": true/false, "data": ..., "error": "...", "message": "..."}`
+
+---
 
 ## Build & Deploy
 
-Source: `https://gitea.dooplex.hu/admin/deploy-felhom-compose` → `controller/` subfolder.
-
-Build happens outside the repo in `~/build/felhom-controller/` to keep the repo clean.
-See `docs/BUILDING.md` for the full guide.
+### Build
 
 ```bash
-# Quick build (current platform only)
+# On build server (192.168.0.180)
 cd ~/build/felhom-controller
-./build.sh 0.2.11
-
-# Build + push to Gitea registry
-./build.sh 0.2.11 --push
+git -C ~/git/deploy-felhom-compose pull
+./build.sh v0.12.2 --push
 ```
 
 ### Deploy on customer node
 
 ```bash
-# Pull new image
-docker pull gitea.dooplex.hu/admin/felhom-controller:0.2.11
-
-# IMPORTANT: use 'up -d', NOT 'restart' — restart doesn't pick up new images
+# On customer node (e.g., 192.168.0.162)
 cd /opt/docker/felhom-controller
-docker compose up -d
+sudo docker pull gitea.dooplex.hu/admin/felhom-controller:v0.12.2
+sudo sed -i 's|image: gitea.dooplex.hu/admin/felhom-controller:.*|image: gitea.dooplex.hu/admin/felhom-controller:v0.12.2|' docker-compose.yml
+sudo docker compose up -d
 ```
 
+**Important:** Always use `docker compose up -d`, NOT `docker compose restart` — restart doesn't pick up new images.
+
+### Docker Requirements
+
+The controller container needs:
+- `privileged: true` (disk operations)
+- Docker socket mount (`/var/run/docker.sock`)
+- `/mnt` mount with `propagation: rshared` (container mounts visible to host)
+- `/dev` mounted as `/host-dev` (block device access)
+- `/etc/fstab` mounted as `/host-fstab` (persistent mount config)
+
+See `docker-compose.yml` for the full volume configuration.
+
+---
+
+## Roadmap
+
+### Completed
+
+- [x] Stack management with deploy flow and memory validation
+- [x] Git-based app catalog sync
+- [x] Central job scheduler
+- [x] System monitoring with SQLite metrics and Chart.js charts
+- [x] Healthchecks.io integration (5 ping types)
+- [x] 3-layer backup system (DB dumps + restic + cross-drive)
+- [x] Per-app backup restore with auto stop/restart
+- [x] Storage management (scan, format, mount, registry)
+- [x] App data migration between storage paths
+- [x] Central hub reporting
+- [x] Email notifications via hub relay
+- [x] Settings persistence and password management
+- [x] Dashboard alert system
+
+### In Progress / Planned
+
+- [ ] Update classification and auto-apply (optional/required/security markers)
+- [ ] Self-update mechanism with health-based rollback
+- [ ] Docker volume backup (`/var/lib/docker/volumes:ro`)
+- [ ] Raspberry Pi testing (pi-customer-1)
+- [ ] Cross-drive restic pruning (unbounded snapshot growth)
+- [ ] CSRF protection on POST endpoints
+- [ ] Login rate limiting
+
+---
+
 ## Test Environments
 
-| Node | Hardware | Domain | IP | Status |
-|------|----------|--------|----|--------|
-| demo-felhom | Acemagic GK3PLUS N100, 16G RAM, 512G SSD + 1TB HDD | demo-felhom.eu | 192.168.0.162 | ✅ Controller v0.10.0 + Paperless-ngx running |
-| pi-customer-1 | Raspberry Pi 3B+, 1G RAM, 32G SD | pi-customer-1.local | — | 📲 Not yet tested |
-
-### First deployment log (Paperless-ngx on demo-felhom)
-
-- **Date:** 2026-02-13
-- **App:** Paperless-ngx (document management)
-- **Deploy method:** Dashboard UI → "Telepítés" button
-- **Issues encountered & resolved:**
-  1. Password fields accepted empty values → Added server-side + client-side validation
-  2. "Telepítés" button appeared for already-deployed apps → Fixed in-memory Deployed flag update
-  3. Green status shown for `(health: starting)` containers → Added health-aware state parsing
-  4. Stack cards switched positions on refresh → Added alphabetical sorting in GetStacks()
-  5. "Részletek" button did nothing for deployed apps → Redirects to deploy page (read-only)
-  6. OCR crash: `PAPERLESS_OCR_LANGUAGE=hun` not installed → Added `PAPERLESS_OCR_LANGUAGES` (plural) to docker-compose
-  7. Container restart vs recreate: `docker compose restart` doesn't pick up new images → Documented: always use `docker compose up -d`
-
-## REST API
-
-| Method | Endpoint | Auth | Description |
-|--------|----------|------|-------------|
-| GET | `/api/health` | No | Health check (for monitoring) |
-| GET | `/api/stacks` | Yes | List all stacks |
-| GET | `/api/stacks/{name}` | Yes | Stack details |
-| GET | `/api/stacks/{name}/deploy-fields` | Yes | Get deploy form fields |
-| POST | `/api/stacks/{name}/deploy` | Yes | First-time deploy with config |
-| POST | `/api/stacks/{name}/start` | Yes | Start stack |
-| POST | `/api/stacks/{name}/stop` | Yes | Stop stack (not protected) |
-| POST | `/api/stacks/{name}/restart` | Yes | Restart stack |
-| POST | `/api/stacks/{name}/update` | Yes | Pull images + recreate |
-| POST | `/api/stacks/{name}/optional-config` | Yes | Update optional config env vars |
-| GET | `/api/stacks/{name}/logs` | Yes | Container logs (add `?raw=1` for plain text) |
-| POST | `/api/stacks/rescan` | Yes | Trigger manual stack discovery |
-| GET | `/api/system/info` | Yes | System resource usage (RAM, disk, CPU, temp, load) |
-| GET | `/api/backup/status` | Yes | Backup status (last run, DB dump count, repo stats) |
-| POST | `/api/backup/run` | Yes | Trigger manual backup (DB dumps + restic snapshot) |
-
-## Status & Roadmap
-
-### Phase 1 — Stack Manager + Deploy Flow ✅ COMPLETE
-- [x] Project skeleton & config format
-- [x] .felhom.yml app metadata format with deploy fields
-- [x] Per-app config persistence (app.yaml)
-- [x] Secret generation engine (password, hex, static)
-- [x] Stack catalog (read compose files + metadata from disk)
-- [x] Docker Compose operations (up/down/pull/ps/logs)
-- [x] Deploy flow with interactive field input
-- [x] Password validation (server-side + client-side, no empty passwords)
-- [x] Basic web dashboard with start/stop/deploy buttons
-- [x] Health-aware container states (starting/unhealthy/running)
-- [x] REST API for stack + deploy operations
-- [x] Simple web authentication (bcrypt sessions)
-- [x] App assets baked into container (SVG/PNG logos, webp screenshots)
-- [x] Container image build pipeline (Dockerfile + build.sh)
-- [x] Build + push to Gitea container registry
-- [x] Deploy on N100 test node — dashboard accessible
-- [x] Stack scanning + display working
-- [x] **First app deployed: Paperless-ngx via dashboard** (2026-02-13)
-- [x] Periodic stack rescanning (every 2 minutes)
-- [x] Alphabetically sorted stack display
-- [x] Deploy page doubles as read-only config viewer for deployed apps
-
-### Phase 2 — Monitoring & Health ✅ COMPLETE
-- [x] System metrics on dashboard (RAM, SSD, HDD usage bars)
-- [x] `/api/system/info` endpoint with live resource data
-- [x] Pre-deploy memory validation (mem_request hard block, mem_limit soft warning)
-- [x] Memory summary bar on deploy page
-- [x] CPU usage collector (background /proc/stat sampling, 5s interval)
-- [x] CPU usage bar on dashboard with load average display
-- [x] Temperature reading from /sys/class/thermal (with /host/sys Docker mount)
-- [x] Temperature display with colored indicator dot (green/yellow/red)
-- [x] Central job scheduler (replaces ad-hoc goroutines)
-- [x] Healthchecks.io-compatible HTTP pinger with retry logic
-- [x] System health checks (disk, memory, CPU, temp, Docker, protected containers)
-- [x] Heartbeat ping (5-minute "I'm alive" signal)
-- [x] SQLite metrics store (system + container metrics, 60s collection, 30-day prune)
-- [x] Backup integrity check (weekly restic check with Healthchecks ping)
-- [x] Customer notifications (email via hub relay + Resend API)
-- [x] Notification preferences sync (controller → hub on save + startup)
-
-### Phase 3 — Backups ✅ COMPLETE
-- [x] DB auto-discovery (PostgreSQL/MariaDB containers via docker inspect)
-- [x] DB dump engine (pg_dump/mariadb-dump via docker exec, atomic writes)
-- [x] Restic integration (auto-init, snapshot, prune, check, stats)
-- [x] Restic password auto-generation (no manual setup needed)
-- [x] Backup orchestrator (DB dumps + restic + weekly prune)
-- [x] Backup status on dashboard (last run, DB count, repo stats)
-- [x] Manual backup trigger from UI ("Mentés most" button)
-- [x] `GET /api/backup/status` and `POST /api/backup/run` endpoints
-- [ ] Restore workflow
-
-### Phase 4 — Git Sync & Updates
-- [x] Periodic git pull for stack definitions (git sync module)
-- [x] Manual sync button on Alkalmazások page ("Sablonok frissítése")
-- [x] Sync status in `/api/system/info`
-- [ ] Update classification (optional/required/security)
-- [ ] Update window enforcement
-- [ ] Dashboard update notifications with "Update" button
-
-### Phase 5 — Self-Update & Resilience
-- [ ] Self-update check & execution
-- [ ] Pre-update config backup
-- [ ] Health-based rollback mechanism
-- [ ] Config export/import
-
-### Phase 6 — Central Management (in progress)
-- [x] Central hub reporting (controller → hub JSON push with Bearer auth)
-- [x] Hub report builder (system, stacks, backup, health, containers, metrics)
-- [x] Hub service (felhom-hub: REST API + SQLite + dark-theme dashboard)
-- [x] K8s manifests for hub deployment on k3s
-- [ ] Fleet-wide update management
-- [x] Customer notifications (email via hub relay)
-- [x] Notification preferences sync (controller → hub)
-- [x] Hub customer detail page: notification preferences + log display
+| Node | Hardware | Domain | Status |
+|------|----------|--------|--------|
+| demo-felhom | Acemagic GK3PLUS N100, 16G RAM, 512G SSD + 1TB HDD | demo-felhom.eu | Controller v0.12.2 running |
+| pi-customer-1 | Raspberry Pi 3B+, 1G RAM, 32G SD | pi-customer-1.local | Not yet tested |
 
 ## Related Repositories
 
@@ -522,5 +724,4 @@ docker compose up -d
 |------------|---------|
 | [deploy-felhom-compose](https://gitea.dooplex.hu/admin/deploy-felhom-compose) | This repo — controller + deploy scripts |
 | [app-catalog-felhom.eu](https://gitea.dooplex.hu/admin/app-catalog-felhom.eu) | Docker Compose templates + .felhom.yml metadata |
-| [felhom.eu](https://gitea.dooplex.hu/admin/felhom.eu) | Website + app assets + felhom infra manifests (incl. felhom-hub) |
-| [homelab-manifests](https://gitea.dooplex.hu/admin/homelab-manifests) | k3s cluster manifests (dooplex.hu) |
\ No newline at end of file
+| [felhom.eu](https://gitea.dooplex.hu/admin/felhom.eu) | Website + app assets + felhom-hub service |