From c446ca072ec948c3da060e4b66c97f6b0bb8a2a3 Mon Sep 17 00:00:00 2001
From: Steve Cliff <steve@devcloud.guru>
Date: Mon, 4 May 2026 23:04:10 +0100
Subject: [PATCH] ui(alerts): make Acknowledge vs Resolve distinction visible

Both buttons make the row leave the Open tab, so on a quiet system
they look identical. The behavioural difference only manifests next
time the underlying condition fires:

  - Acknowledge silences fan-out while the problem persists; the
    alert parks on the Acknowledged tab and recurrences just touch
    last_seen_at without re-notifying.
  - Resolve closes the alert. If the same condition fires again
    later, a fresh alert with a new id raises and the channels
    fan out as if it were the first time.

Add a one-line legend under the page header explaining both, and
title= tooltips on each button covering the same ground for keyboard
and assistive tech.
---
 web/templates/pages/alerts.html       | 7 +++++++
 web/templates/partials/alert_row.html | 9 ++++++---
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/web/templates/pages/alerts.html b/web/templates/pages/alerts.html
index f7475fd..5f6db06 100644
--- a/web/templates/pages/alerts.html
+++ b/web/templates/pages/alerts.html
@@ -28,6 +28,13 @@
     </div>
   </div>
 
+  {{/* triage legend — Acknowledge vs Resolve looks identical on screen
+       (both leave the Open tab) so the difference needs spelling out. */}}
+  <div class="text-ink-mute mt-2 leading-[1.55]" style="font-size: 11.5px; max-width: 760px;">
+    <span class="text-ink-mid">Acknowledge</span> silences fan-out while the underlying problem is still happening — the alert moves to the Acknowledged tab.
+    <span class="text-ink-mid">Resolve</span> closes the alert; the next failure raises a fresh one with a new notification.
+  </div>
+
   {{/* filter strip */}}
   <div class="panel mt-4 px-4 py-3 rounded-[7px]"
        style="display: grid; grid-template-columns: auto auto auto 1fr; gap: 14px; align-items: center;">
diff --git a/web/templates/partials/alert_row.html b/web/templates/partials/alert_row.html
index b194386..7cabdc1 100644
--- a/web/templates/partials/alert_row.html
+++ b/web/templates/partials/alert_row.html
@@ -69,13 +69,15 @@
         {{if $qs}}<input type="hidden" name="qs" value="{{$qs}}">{{end}}
         <button type="submit" class="btn"
                 hx-post="/alerts/{{$a.ID}}/acknowledge{{if $qs}}?{{$qs}}{{end}}"
-                hx-swap="none">Acknowledge</button>
+                hx-swap="none"
+                title="I've seen this — silence further fan-out, but the alert is still open until the condition clears or you Resolve it.">Acknowledge</button>
       </form>
       <form method="post" action="/alerts/{{$a.ID}}/resolve">
         {{if $qs}}<input type="hidden" name="qs" value="{{$qs}}">{{end}}
         <button type="submit" class="btn"
                 hx-post="/alerts/{{$a.ID}}/resolve{{if $qs}}?{{$qs}}{{end}}"
-                hx-swap="none">Resolve</button>
+                hx-swap="none"
+                title="The underlying issue is fixed. Closes the alert. If the condition fires again a fresh alert will be raised with a new fan-out.">Resolve</button>
       </form>
     {{else if eq $status "acknowledged"}}
       <span class="text-ink-fade" style="font-size: 11px;">
@@ -85,7 +87,8 @@
         {{if $qs}}<input type="hidden" name="qs" value="{{$qs}}">{{end}}
         <button type="submit" class="btn"
                 hx-post="/alerts/{{$a.ID}}/resolve{{if $qs}}?{{$qs}}{{end}}"
-                hx-swap="none">Resolve</button>
+                hx-swap="none"
+                title="The underlying issue is fixed. Closes the alert.">Resolve</button>
       </form>
     {{else}}
       <span class="text-ink-fade" style="font-size: 11px;">resolved · {{relTime $a.ResolvedAt}}</span>